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Preface 



This publication is an introduction to, and 
a user's guide and reference manual for, 
all general users of the VM/370 command 
languages (CP and CHS) . 

It contains only those commands 
available for general users; other commands 
are listed in the publications IBM Virtual 
Machine Facility/370: Operator's Guide, 
Order No. GC20-1806, IBM Virtual Machine 
Facility/370: System Programmer's Guide, 
Order No. GC20-1807, and IBM Virtual 
Hil£hine Facility/370: Remote Spooling 
Communications Subsystem (RSCS) User's 
Guide, Order No. GC20-1816. 

The publication is organized in two 
parts: "Part 1: Osage Information" and 
"Part 2: Reference Information". 



machine. It includes information about the 
virtual machine console, attaching devices, 
handling tape drives, loading operating 
systems, spooling the console, reading 
cards, printing, punching, disconnecting 
the terminal, and alternating execution of 
operating systems in one virtual machine. 



Part 2 is in two sections: 

"Section 7: Format and Usage Rules for 
CMS Commands" and "Section 8: Format and 
Usage Rules for CP Commands" provide you 
with all the information you need to use 
the commands and facilities of VM/370. 
Also included is a summary of the 
notational conventions used to describe the 
commands. 



Part 1 has six sections: 

"Section 1 : Introduction and General 
Concepts" is a summary of general concepts 
you should be familiar with when you are 
using VM/370. 

"Section 2: The VM/370 CP and CMS 
Command Languages" describes the VM/370 
command environments, the general structure 
of the command language, and, in general, 
how to use the features of the VM/370 
command languages to help you solve 
programming problems. 

"Section 3: CMS Virtual Disks and How to 
Use Them" describes the virtual disk system 
for your virtual machine and how to use 
it. 

"Section 4: The CMS File System" 
describes the file as it is used in the CMS 
system. This section gives you information 
on how to create and name a file, how files 
are used in the system, and how CMS handles 
OS data sets and DOS files. 



"Secti 
Sample 
introduct 
programmi 
you are g 
at your 
Together 
preceding 
should 
informati 
machine a 



on 5 

Progr 

ion 

ng en 

iven 

termi 

with 

sec 
provi 
on yo 
nd it 



: Writing 
am Usin 
to the 
vironment. 
a program 
nal as y 
the infor 
tions, th 
de you 
u need to 
s interact 



and 

g CMS 

VM/370 

In t 

that y 

ou rea 

mation 

is sam 

with 

use y 
ive cap 



Executin 
" is 

interac 
his sect 
ou can e 
d the b 
in the 
pie pro 

the b 
our vir 
abilitie 



g a 
an 
tive 
ion, 
nter 
ook. 
four 
gram 
asic 
tual 
s. 



The "Appendixes" 
information. They 
functions performe 
information on how 
how to use the CMS 
of macros you ca 
assembler, a chart 
related to files 
commands, and a lis 
by VM/370. 



include more 
include a lis 
d by VM/370 
to debug usin 
Batch Facility 
n use with th 
showing the 
manipulated 
t of filetypes 



reference 
t of the 
commands, 
g VM/370, 
a list 
e VM/370 
filemodes 
by CMS 
reserved 



In this publication, the following 
terminology is used: 



IBM 3330 Disk Storage Models 1, 2, and 
11, and the IBM 3333 Disk Storage and 
Control Models 1 and 11. 

2305 refers to the IBM 2305 Fixed Head 
Storage, Models 1 and 2. 



3270 refers 
Station. 



to the 3277 Display 



"Section 6: Virtual Machine Operation" 
describes the operation of a virtual 



Any information pertaining to the IBM 
2741 terminal also applies to the IBM 
3767 terminal unless otherwise noted. 



For a glossary of VM/370 terms see the 
IBM Virtual Machine Fac il i ty/3 7 : glossary 
and Master Index, Order No. GC20-1813. 



PREREQUISITE PUBLICATIONS 



You should be familiar with the information 
in the publications listed on the front 
cover before you use this publication. 



If the IBM 3767 Communication Terminal 
is a virtual console, the publication IBM 
3767 Operator's Guide, Order Ho. GA 18-2000, 
is also a prerequisite. 



COREQUISITE PUBLICATIONS 

The information in the following 
publications describes certain VM/370 
facilities in greater detail and with more 
examples than can be contained in this 
publication: 

III Virtual Machine Faci lity./3 7 : 

EDIT Guide, Order Ho. GC20-1805 

EXEC Dser«s Guide, Order No. GC20-1812 



Sis tern Programmer 's Guide, Order No. 
GC20-1807 

System Messages, Order No. GC20-1808 

Glossary and Master Index, Order No. 
GC20-1813 

Remote Spooling Communications 
Subsystem (RSCS) User's Guide, Order 
No. GC20-1816 

Q s ./VS-VM/370 Assembler Programmer's Guide, 
Order No. GC33-4021 



References in text to titles of 
prereguisite and coreguisite VM/370 
publications will be given in abbreviated 
form. 
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Summary of Amendments 

for GC20-1804-3 

VM/370 Release 2 PLC 13 



VM/370 MEASUREMENT FACILITY 



IBM 3270 REMOTE SUPPORT 



New: Program Feature 

A new class G command, INDICATE, allows you 
to display, at your terminal, certain 
system load conditions and your virtual 
machine's use of system resources. The 
following changes to this manual reflect 
this support: 

• "section 8: Format and Osage Rules for 
CP Commands" is updated to include the 
new INDICATE command. 

• "Figure 34. Commands Accepted from Each 
Oser Class" is updated. 

• "Figure 35. CP Command Summary" is 
updated. 

• "Figure 44. Commands for System and 
Hardware Analysis" is updated. 



VM/VS HANDSHAKING FEATORE 



New: Programming Feature 

The VM/VS Handshaking feature is a 
communication path between VM/370 and 
0S/VS1 that makes each system control 
program aware of certain capabilities and 
requirements of the other. The following 
changes to this manual reflect this 
support: 

• A new operand, PAGEX, is added to the CP 
SET command. 

• The response for the CP QUERY SET 
command line is updated. 

• "Figure 34. Commands Accepted from EAch 
User Class" is updated. 

• "Figure 41 Commands for Virtual Machine 
Control is updated. 



New: Program Feature 

VM/370 now supports the IBM 3270 
Information Display System as a remote 
virtual machine console attached via 
nonswitched point-to-point lines to a 2701 
Data Adapter Unit, 2703 Transmission 
Control Unit, or 3704/3705. Communications 
Controller in emulation mode. The remote 
3270 user also has the capability of 
copying an entire screen display on a 3284, 
3286, or 3288 Printer at the remote 
location. 

The following changes to this manual 
reflect this new support: 

• "Section 7. Format and Usage Rules for 
CMS Commands" is updated to reflect 
additional operands and subcommands of 
the EDIT command. 

• "Section 8. Format and Usage Rules for 
CP Commands" is updated to include the 
COPY function of the SET command. 

• "Figure 34. Commands Accepted from Each 
User Class", "Figure 36. Commands to 
Control a Terminal Session", and "Figure 
42. Commands to Control VM/370" are 
updated to reflect additional operands 
to the NETWORK, QUERY, and SET 
commands. 



NEW OPERANDS FOR SET COMMAND 



New: Program Feature 

Two new operands to 
described in "Section 8 
Rules for CP Commands" 



the SET command 

Format and Usage 

allow the virtual 



machine user to enable and disable the 
ECMODE and/or ISAM options, dynamically. 
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NEW OPERAND FOR SLEEP COMMAND 



MISCELLANEOUS 



New: Program feature 



Changed: Documentation Only 



A delay time interval may now be specified 
as an operand on the SLEEP command line. 
The use of this optional operand causes the 
virtual machine to automatically awaken at 
the end of the specified time interval. 
The new command format is described in 
"Section 8: Format and Usage Rules for CP 
Commands" . 



This Technical Newsletter contains other 
minor technical and typographic changes. 
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NEW DEVICE SUPPORT 



neji; ri.Oyj.diu r eat lire 

The IBM 3340 Direct Access Storage Facility 
is now supported by VM/370. This support 
includes Rotational Position Sensing (RPS) 
and the 3348 Data Module, Models 35, 70 and 
70F (supported as a Model 70) . The 
following changes to this manual reflect 
this support: 

• The control statements and messages of 
the DASD Dump Restore program are 
updated. 

• T3340 is a new operand for the CP DEFINE 
command. 

• The device type field in the response 
for the CP QUERY VIRTUAL DASD command 
line is updated. 

VM/370 supports the IBM 3767 Communication 
Terminal (at 300 bps) operating as an IBM 
2741 Communication Terminal only. No 
coding changes were necessary; the 
following changes to this manual reflect 
this support: 

• The list of prereguisite publications in 
the Preface is updated. 



"Section 
updated. 



The CMS File System" is 



"The Terminal 



discussion in "Section 5: Writing and 
Executing a Program Using VM/370" is 
updated. 

The discussions of the BLIP and AUTOREAD 
functions of the CMS SET command are 
updated. 

The discussion of the APL operand of the 
CP TERMINAL command is updated. 



READING DOS FILES FROM DOS DISKS 



New: Programming Feature 

Using OS macros, CMS can now read DOS files 
that reside on DOS disks. No DOS macros 
are simulated. The following changes to 
this manual reflect this support: 



The CMS ACCESS, FILEDEF, LISTDS, 
MOVEFILE, and STATE command descriptions 
in "Section 7: Format and Usage Rules 
for CMS Commands" are updated. 

"Figure 37. Commands to Develop Programs 
and Process Data" is updated. 



CMS ZAP SERVICE PROGRAM ENHANCED 



New: Program Feature 

The CMS ZAP service program is enhanced so 
that it can now modify or dump TXTLIB and 
MODULE files in addition to LOADLIB files. 
"Figure 13. CMS Command Summary" is updated 
to reflect this support. This service 
program is intended for use by system 
support personnel only. 



NEW SUBSYSTEM SUPPORTED AS VM/370 COMPONENT 



New: Component 



The 



Remote Spooling 



Communications 



Your Virtual Console" Subsystem 



VM/370 component. RSCS transmits spool 
files across a teleprocessing network to 
and from remote stations. Remote stations 
supported include HASP- and ASP-type batch 
processors and work stations. The new 
component is a control program designed to 
run in a virtual machine dedicated to 
remote spooling. The following changes 
reflect this support: 

• The Preface is updated. 

• "Section 1: Introduction and General 
Concepts" is updated. 

• "Figure 34. Commands Accepted from Each 
Privilege Class" is updated. 

• "Figure 35. CP Command Summary" is 
updated. 

• The CP CHANGE, DEFINE, DETACH, ORDER, 
SET, SPOOL, and TRANSFER command 
descriptions are updated. 



• A new CP coinand, TAG, is described. 

• "Figure 36. Commands to Control a 
Terminal Session" is updated. 

• "Figure 43. Commands for Spooling 
Control" is updated. 

• "Appenidx C: Using the CBS Batch 
Facility" is updated. 



ENHANCEMENT FOR THE VIRTUAL MACHINE 



New: Program feature 

Programs using block multiplexer channel 
operations (for example, DOS/VS, VS1 , and 
VS2) can now be executed in block 
multiplexer mode on the virtual machine. 
This virtual machine option may increase 
the throughput of the virtual machine's 
operating system because it allows the 
overlap of SIOs to virtual devices without 
encountering the channel busy condition. 
The following changes to this publication 
reflect this support: 

• "Figure 34. Commands Accepted from Each 
Privilege Class" is updated. 

• The CP DEFINE and QUERY commands have a 
new operand, CHANNELS. 



MISCELLANEOUS 



Changed: Documentation Only 

Numerous minor editorial changes have been 
made; these are too numerous to mention. 
However, a list of the major editorial 
changes and all miscellaneous technical 
changes follows. 

"Part 1 : Usage Information" has many 
editorial changes. In addition, several 
sections about the operation of virtual 
machines and CMS, which were in the VM/370: 
Planning and System generation Guide, are 
now included in Part 1: 

• Additional information about the 
terminal mode of operation, attention 
interrupts, and the CMS command search 
order is included in "Section 2: The 
VM/370 CP and CMS Command Languages." 

• Additional information about accessing 
CMS disks is added to "Section 3: CMS 
Virtual Disks and How to Use Them." 

• Additional information about compiling 
programs under CHS and tape handling in 



CMS is included in "Section 4: The CMS 
File System. " 

• Additional information about entering 
the continuation character in column 72 
is included in "Section 5: Writing and 
Executing a Sample Program using CMS." 

• A new section, "Section 6: Virtual 
Machine Operation" is added to Part 1. 

"Part 2: Reference Information" has the 
following changes: 

• The "Notational Conventions" section is 
expanded. 

• "Figure 13. CMS Command Summary" 
contains editorial changes. 

• The following CMS command descriptions 
are clarified: 

-ACCESS 

-ASSEMBLE 

-COMPARE 

-COPYFILE 

-DDR control statements 

-EDIT 

-ERASE 

-EXEC 

-FILEDEF 

-FORMAT 

-GENDIRT 

-GENMOD 

-GLOBAL 

-INCLUDE (Two new options, DUP and 

NODUP, are described) 
-LISTFILE 
-LOAD (Two new options, DUP and NODUP, 

are described) 
-PRINT 
-PUNCH 
-QUERY 
-READCARD 
-RELEASE 
-RENAME 
-RUN 
-SET 
-START 
-STATE 
-SVCTRACE 
-SYNONYM 
-TAPE 
-TAPPDS 
-TXTLIB 
-TYPE 
-UPDATE 

• "Figure 17. Summary of EDIT Subcommands 
and Macros" contains editorial changes. 

• Two previously undocumented immediate 
commands RO and SO are now included. SO 
temporarily suspends the recording of 
trace information and RO restarts 
tracing that was suspended via the SO 
command. 



"Figure 33. CP Privilege Class 
Descriptions" is updated. 

"Figure 34. Commands Accepted from Each 



"Figure 35. CP Command Summary" is 
updated. 

The following CP command descriptions 
are clarified: 



-EXTERNAL 

-IPL 

-LINK 

-LOGOFF 

-LOGON 

-MESSAGE 

-QUERY 

-SET 

-TERMINAL 

-TRACE 

-TRANSFER 



-#CP 

-CLOSE 

-CP 

-DEFINE 

-DISCONN 

-DISPLAY 

-DUMP 



The RDTAPE and PRINTL macro descriptions 
in "Appendix D: CMS Macro Instructions" 
are clarified . 



"Figure 48. 
updated. 



Reserved Filetypes" is 
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CMS EDITOR LINE RENUMBERING FEATURE 

New: Program Feature 

A new CMS Editor subcommand recomputes 
the line numbers of VSBASIC and FREEFORT 
source files. "Figure 13. Summary of 
EDIT Subcommands" and the EDIT command 
error messages in "Section 6: Format 
and Usage Rules for CMS Commands" were 
changed to support this feature. 



IBM 3704/3705 COMMUNICATIONS CONTROLLERS 
NETWORK CONTROL PROGRAM (NCP) AND 
PARTITIONED EMULATION PROGRAM (PEP) SUPPORT 

New: Program Feature 

VM/370 now support all three of the 
3704/3705 control programs: 

• Emulation Program (EP) 

• Network Control Program (NCP) 

• Partitioned Emulation Program (PEP) 



The following 
support 



changes reflect this 



The Preface is updated to remove the 
statement limiting support of the 
3704/3705. 



"Figure 31. CP Command Summary" in 
"Section 7: Format and Usage Rules 
for CP Commands" is updated. 

The DIAL, DISCONN, LOGON and LOGOFF 
descriptions in "Section 7: Format 
and Usage Rules for CP Commands" are 
updated. 

"Figure 38. Commands to Control 
VM/370" in "Appendix A: Functions of 
VM/370 Commands" is updated. 

"Figure 43. Disk Determination" in 
"Appendix E: Disk Determination 
(Filemode Management) " is updated. 

"Figure 44. Reserved Filetypes" in 
"Appendix F: Reserved Filetype 
Descriptions" is updated. 



MISCELLANEOUS 

Changed: Documentation Only 

• The running foot for section 7 is 
corrected on the TNL pages to read 
"Section 7: Format and Usage Rules 
for CP Commands" 

• The Index is corrected. 



f» C M C f .-. : 



j . cno command summary" in 
"Section 6: Format and Usage Rules 
for CMS Commands" is updated. 
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CHANGES TO GENERAL INFORMATION IN PART J 

New: Documentation Change 

Part 1 of the publication has been 
changed to include information on 
general concepts for VH/370 users, on 
the Cp and CHS command languages, on the 
CHS disk system, and on the CHS file 
system. Also, there is an example 
program for use as an introduction to 
the interactive processing capabilities 
of VH/370. 



GENERAL CHANGES TO PUBLICATION 

C ha nged; Documentation expanded 

Editorial changes have been made 
throughout the publication to clarify 
usage. 

New: Documentation Change 

In Section 6, "Format and Osage Rules 
for CHS Commands", the error messages 
and return codes have been included in 
the command descriptions. 



CHANGES TO CHS COHHANDS 

Changed : Documentation Expanded 

SYNONYH COHHAND 

Opdated to charify use of the command. 

Changed: Program Feature 

ACCESS COHHAND 

Opdated to clarify its use with OS 
Read/Only disk. 

DDR COHHAND 

Opdated to support 9-track 6250 bpi 
tapes and 3330 Hodel 11 disks. 

EDIT COHHAND 

Opdated to support new subcommands for 
graphic display devices. 

FILEDEF COHHAND 

Opdated to reflect new support for 
dynamic entry of a data set name and for 



new options HEHBER and CONCAT. Also, 
6250 bpi tapes are now supported by 
FILEDEF. 



of the new 



GLOBAL COHHAND 

Opdated to support use 
FILEDEF CONCAT option. 

HOVEFILE COHHAND 



Updated to include support for accessing 
OS data sets. 



QOERY COHHAND 

Updated to include support for guerying 
the status of OS disks accessed by CHS. 



SET COHHAND 

Opdated to include support for setting 
conditions for use with a display 
terminal. 



STATE COHHAND 

Opdated to include support for verifying 
the existence of an OS disk accessed by 
CHS. 

TAPE COHHAND 

Opdated to include support for 6250 bpi 
tapes. 

OPDATE COHHAND 

Opdated to allow flexibility in format 
specification of auxiliary files. 



New: Program Feature 

ASSEHBLE COHHAND 

Opdated to reflect the new options for 
the assembler and to clarify use of the 
command. 

LISTDS COHHAND 

Added to the system: Lists information 
about data sets on OS disks accessed by 
CHS. 



CHANGES TO CP COHHANDS 

Changed: Documentation Expanded 
* (asterisk) COHHAHD 
Updated to clarify its use. 

ADSTOP COHHAHD 

Updated to clarify use of the VH/370 
virtual machine assist feature with 
ADSTOP. 

CHANGE COHHAND 

Updated to clarify use. 

CLOSE COHHAND 

Updated to clarify use. 

DISCONN COHHAND 

Updated to clarify use. 

IPL COHHAND 

Updated to clarify use. 

LOGOFF COHHAND 

Updated to clarify use. 

LOGON COHHAND 

Updated to clarify use. 

BEHIND COHHAND 

Updated to clarify use. 

SET COHHAND 

Updated to clarify use. 

SLEEP COHHAND 

Updated to clarify use. 

TRACE COHHAND 

Updated to clarify use. 



Changed: Program Feature 

DEFINE COHHAND 

Updated to include support for the GRAF 
operand. GRAF allows you to define a 
temporary graphic device for your 
virtual machine. 

DISPLAY COHHAND 

Updated to allow you to specify a range 
of registers or storage. 

DUHP COHHAND 

Updated to allow you to specify a range 
of registers or storage. 

HESSAGE COHHAND 

Name of the HSG command has been changed 
to HESSAGE. 

QUERY COHHAND 

Updated to support GRAF, and PFnn 
operands. These new operands allow you 
to guery the status of console spool 
files, display terminals, and program 
function keys, respectively. 

SET COHHAND 

Updated to include support for the 
ASSIST and PFnn options. ASSIST invokes 
the virtual machine assist feature; PFnn 
allows you to define functions 
associated with program function keys on 
a graphic display terminal. 

SPOOL COHHAND 

Updated to support the * (asterisk) 
character option. * specifies a 
universal spooling class which allows 
your virtual reader to read all classes 
of spool files. 

Also, the CLOSE, FOR, and PURGE options 
are supported. 

TERHINAL COHHAND 

Updated to clarify use. Also, updated 
to reflect support for the HODE operand, 
which allows you to set the mode of your 
terminal to either CP mode (Control 
Program) or VH (virtual machine) . 

TRANSFER COHHAND 

Updated to support the FROH userid 
operand, which allows you to reclaim a 
file that you spooled to another user. 



New: Program Feature 

#CP COMMAND 

Added to allow you to enter CP commands 
from a virtual machine environment 
without Issuing an interrupt. 

ATTN COMMAND 

Added to allow an attention interrupt to 
be entered at the keyboard. 



CP COMMAND 

Added to allow entry of the characters 
"CP" while processing in the CP command 
environment. 

REQUEST COMMAND 

Added to allow you to enter an attention 
interrupt at the keyboard of you virtual 
console. 
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Part 1: Usage Information 



This part of the publication contains rules and information to help you 
use all of the facilities of VM/370. It contains six sections. 

"Section 1 : Introduction and General Concepts" is a summary of 
general concepts you should be familiar with when you are using VM/370. 

"Section 2: The VM/370 CP and CMS Command Languages" describes the 
VM/370 command environments, the general structure of the command 
language, and how you can use the features of the VM/370 command 
languages to aid you in solving programming problems. 

"Section 3: CMS Virtual Disks and Bow to use Them" describes the 
virtual disk system for your virtual machine and how to use it. 

"Section 4: The CMS File system" describes the file as it is used in 
the CMS system. This section gives you information on how to create and 
name a file, how these files are used in the system, and how CMS handles 
| OS data sets and DOS files. 

"Section 5: Writing and Executing a Sample Program Using CMS" is an 

introduction to the VM/370 interactive programming environment. In this 

introductory section, you are given a program that you can enter at your 

terminal as you read the book. Together with the information in the four 

preceding sections, this sample program should provide you with the 

basic information you need to use your virtual machine and its 
interactive capabilities. 

"Section 6: Virtual Machine Operation" contains additional 
information about operating virtual machines. This information 
generally applies to non-CMS virtual machines and includes an example of 
alternately executing CHS and another operating system in the same 
virtual machine. 
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Section 1: Introduction and General Concepts 



This section is a summary of general concepts that are useful to you 

when you are using VM/370. It is a prologue to the following sections, 

which describe how to use virtual disks, and how to use the CHS file 
system. 

Virtual Machine Facility/370 (VM/370) is a system control program 
that controls "virtual machines." A virtual machine is the functional 
eguivalent of a real machine, but where the real machine has lights to 
show status, and buttons and switches on the real system console to 
control it, the virtual machine has a virtual system console to display 
status and a command language to start operations and control them. The 
virtual system console is your terminal; there are three command 
languages, the CP, CMS, and RSCS Command Languages, using your terminal 
(as a virtual console) and the command languages, you have many of the 
capabilities of the operator of a real machine. 



VM/370 Control Program (CP). the Conversational Monitor System (CMS), 
and the Remote Spooling Communications Subsystem (RSCS) 

VM/370 has three components: the Control Program (CP) , the 
Conversational Monitor System (CMS) , and the Remote Spooling 
Communications Subsystem (RSCS) . CP controls the resources of the real 
machine; that is, the physical machine in your computer room. CMS is the 
conversational operating system designed specifically to run under CP. 
RSCS is a subsystem designed to supervise transmission of files across a 
teleprocessing network controlled by CP. This section describes CP and 
CMS; for information about RSCS, see the VM/370: Remote Spooling 
Communications Subsystem (RSCS) User^s Guide. 



THE VIRTUAL MACHINE 

The virtual machine is a software counterpart of a real machine. Its 
control program can be any of those supported by VM/370. These are 
listed in the VM/370: Introduction. 

The virtual machine components are the virtual system console (your 
terminal) , a virtual CPU, virtual storage, and virtual channels and 
input/output (I/O) devices. 

Your virtual machine is a logical extension of the real computer. The 
virtual machines are defined in the VM/370 directory, which is a list of 
all the virtual machines logically extended from the real machine. Each 
entry in the VM/370 directory lists the configuration of a virtual 
machine. 



I2.SI liliijal Disks 

A virtual disk is a logical subdivision of a real disk. For practical 
purposes, it is the same as a real disk on a real machine. Virtual disks 
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have their own device addresses and cylinder numbers. Each CHS virtual 
disk has a Master File Directory that lists each of the files contained 
on it. 

The size of your virtual disks is defined in the VH/370 directory 
entry for your virtual nachine. The virtual disk can be equal to or 
less than the size of the real disk. For CMS, the maximum size of a 
virtual disk is less than the real disk and varies with the device type. 
If you need more space, your system programmer can give it to you by 
redefining the number of cylinders, by defining more disks in your 
VM/370 directory entry; or you can assign temporary disk (T-disk) space 
for your virtual machine. With CMS, you can have up to ten virtual 
disks logically attached to your virtual machine. These ten disks are 
called the A, B, C, D, E, F, G, S, Y, and Z disks and are described in 
more detail in Section 3. 



VM/370 Files 

The file is the essential data unit in the VM/370 system. Programs, 
program input, procedures, and any other type of data unit you want to 
use on the system, are files in the VM/370 system. 

In CMS, a file is a logically related group of records that you 
create. Using the EDIT command, you can create and modify a file 
yourself in the CMS command environment; using FILEDEF, you can define 
OS data sets and DOS files as files for use under CMS. 



Spooling in VM/370 

On a real machine, spooling is, in general, the process of transmitting 
a unit record file from the CPU to a peripheral device for processing or 
from a device to the CPU for processing. When the file is sent to the 
peripheral device, the CPU is free for more work. 

The concept of spooling also applies to virtual unit record I/O 
devices. You process virtual unit record files in your virtual machine 
and, while they are processing, transmit them to your virtual printer or 
to your virtual punch. Your virtual machine is then available for more 
work. This collection of data directed to your virtual printer or punch 
is called a spool file. The output spool file can be transmitted to its 
counterpart on the real machine, to your own reader, or to the reader of 
another virtual machine. Thus, the spool file is waiting to be 
processed by a real device or another virtual machine. 

VM/370 expands the concept of spooling to include the creation of a 
spooled console log which is a record of all of your virtual console 
input/output, including CP commands and responses. This console spool 
file can be sent to the real printer when you want a copy of it. 

The Remote Spooling Communications Subsystem (RSCS) lets you transmit 
files across a teleprocessing network to geographically remote locations 
via the CP TAG and SPOOL commands. For details on how the network is 

| structured and operated, see the VM/370; Remote Spooling Communications 

I Subsystem (RSCS) User^s Guide. 
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THE CP AND CHS COMMAND LANGUAGES 

You control your virtual lachine using the CP and CHS command languages. 
Any virtual machine can use the CP command language; you can use the CHS 
command language only if your virtual machine operating system is CHS. 



lie CP Command Lang uage 

The CP command language gives you control of the devices attached to 
your virtual machine. Hany of the functions of a real computer console 
are simulated via the CP command language. Also, there are commands 
that provide spooling and disk-sharing capabilities. 

CP commands fall into one or more privilege classes; this publication 
provides information on only those commands that can be used by the 
general user (class G) or any user (class any) . General users are those 
users who program, test, and execute applications on a virtual machine. 
The CP command privilege classes available to your virtual machine are 
defined in your VH/370 directory entry. 

Using CP commands, you can send messages to the VH/370 system 
operator and other users, modify the configuration of your virtual 
machine, and use the virtual machine input/output devices. CP commands 
are available to all virtual machines under VH/370. Tou can invoke these 
commands when you are in the virtual machine environment using CHS (or 
some other operating system) in your virtual machine. 



The CHS Command Language 

The CHS command language allows you to create, modify, debug, and, in 
general, manipulate a system of files. 

Hany language processors can be executed under CHS: the assembler, ?S 
BASIC, OS FORTRAN IV, OS COBOL, and OS PL/I Optimizing and Checkout 
Compilers. You can find a complete list of language processors that can 
be executed under CHS in the VH/370: Introduction. CHS executes the 
assembler and the compilers when you invoke them with CHS commands. The 
ASSEHBLE command is described in this manual; the supported compiler 
commands are described in the appropriate Program Product 
documentation. 

The CMS EDIT command allows you to create and modify files; the EXEC 

| command helps you to create a procedure consisting of CP and CMS 

commands, which has the conditional execution capability of a macro 

language; the DEBUG command gives you several program debugging 

subcommands. 

Other CHS commands allow you to read cards from a virtual card 
reader, punch cards to a virtual card punch, and print records on a 
virtual printer. Hany commands are provided to help you manipulate your 
virtual disks and files. 

Since you can invoke CP commands from within the CHS virtual machine 
environment, the CP and CHS command languages are, for practical 
purposes, a single, integrated command language for CHS users. 



Section 1: Introduction and General Concepts 13 



Section 2: The VM/370 UF and UMb Uommand Languages 



This section describes the vh/370 command environments, the general 
structure of the CP and CHS command languages, the user-defined 
commands, command abbreviations, truncations, synonyms, and the command 
search order. 

The VM/370 system is comprised of the Control Program (CP) and the 
Conversational Monitor System (CMS) . CP controls the real machine. You 
can use CP commands to manipulate your virtual machine. CMS is an 
interactive system designed specifically for use with CP for problem 
solving and program development. CMS gives you a file system and the 
commands reguired to manipulate files, and the virtual disks on which 
they reside. 

There are two types of VM/370 commands: system commands and 
user-defined commands. The system commands are those defined by the CP 
and CMS command languages. User-defined CMS commands are those you 
create yourself using the EXEC command or the LOAD and 6ENM0D commands. 
User-defined CP commands are also allowed; your installation system 
programmer must create them. The procedure is described in the VM /370 ; 
System Programmer's Guide. 

Depending on the way you are using the system, you may want to be in 
a specific command environment. A command environment is the environment 
of your virtual machine as defined by the command language subset you 
are using. If you are using the CP command language, you are in the CP 
command environment; if you are using CMS or another operating system, 
you are in the virtual machine command environment. 

Many commands can also have abbreviations and minimum truncations, as 
defined by the system, and can have synonyms, which you define. 

Since there are many types of commands, VM/370 provides a set of 
conventions for searching through the system for a given command. For 
example, you may have defined your own command with the same name as a 
CMS system command, therefore, you must know which command actually 
executes. The rules governing the search for the correct command are 
contained in this section. 



VM/370 Command Environments 

There are two basic command environments: the CP command environment and 
the virtual machine command environment. 

The CP command environment is reached when you log on to VM/370 and 
issue CP commands. Depending on the task you want to perform on your 
virtual machine, you may want to switch in and out of this environment. 
The means for entering and exiting from this environment are described 
in "Interrupting the Execution of a Command" in this section. 

You can find out which command environment you are in by entering a 
null line (that is, pressing the Enter key, or eguivalent, with no 
data) . VM/370 responds to a null line by displaying the current command 
environment. 
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The virtual machine command environment is the environment you reach 
when you load your virtual machine with the CHS operating system or 
another operating system. 

When you load CHS in your virtual machine, you can use both the CP 
and CHS command languages. The CHS command environment has three 
subcommand environments that are entered by means of the EDIT, EXEC, and 
DEBUG commands. 

The EDIT command places your virtual machine in the EDIT subcommand 
environment, where you can use the CHS Editor to create and modify 
files. In the EDIT subcommand environment, you can place your virtual 
machine in either of two modes, the EDIT mode or the INPUT mode. EDIT 
mode lets you modify a file; INPUT mode lets you create or add to a 
file. 

The EXEC subcommand environment is entered via the EXEC command. In 
this environment, you execute procedures that contain combinations of CP 
and CHS commands to perform the functions you specify. These procedures 
are usually created in the EDIT environment. 

The DEBUG command places your virtual machine in the DEBUG subcommand 
environment, in which you can issue commands to display registers and 
storage, specify breakpoints (address instruction stops) , display the 
contents of control words, and so on. 



How to Enter CP and CMS Commands 



A VH/370 command consists of a command name, usually followed by one or 
more positional operands and, in some cases, by an option list. The 
general form for the command line is: 



| command name | [operand...] [ (option. ..[) ]] 



You must use one or more blanks to separate each entry in the command 
line unless otherwise indicated. 



THE COHHAND NAHE 



The command name is an alphameric symbol of not more than eight 
characters. In general, the names are verbs which describe the function 
you want the system to perform. For example, you may want to find out 
whether a certain user is logged on the VH/370 system. In this case, 
you would use the CP QUERY command. 



THE COHHAND OPERANDS 



The command operands are keywords and positional operands of no more 
than eight alphameric characters each. The operands specify the 
information on which the system operates when it performs the command 
function. For the QUERY command, for example, you could use the USER or 
userid operand to find out whether the user is on the system. 
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Some comnands require no operands; others reguire several. You can 

find each class G, class Any, and CHS command with all of its operand 
requirements in Part 2 of this publication. 

You Bust write the operands in the order in which they appear in the 

command formats in Part 2, unless otherwise specified. When you are 

using CHS, blanks should be used to separate the last operand and the 
option list. 



THJ3 CUHH&ND options 

The command options are keywords used to control the execution of the 
coimand. The command formats in Part 2 show all the options for each 
command. 

The option list must be preceded by a left parenthesis; the closing 
parenthesis is not necessary. 

If conflicting or duplicate options are entered, the last entered is 
the option in effect for the command. Exceptions to this rule are the 
CHS COPYFILE, FILEDEF, ERASE, and FORMAT commands. See the individual 
descriptions of these commands in Part 2 for more information. 



COHHEHTS IN THE CP AND CHS COHHAND LANGUAGES 

You can write comments with CP commands of the following types: 

• Commands with no operands 

• Commands with a fixed number of operands 

• Commands with a single optional operand 

You cannot write comments with commands that have a variable number 
of operands or with commands that have more than one optional operand. 

If you want to write comments with CHS commands, you enter them 

following the closing parenthesis of the option list. The only 

exception to this rule is the ERASE command, for which comments are not 
allowed. 

You can enter comments on your console by using the CP * command. 



CHARACTER SET USAGE 

CP and CHS commands may be entered using a combination of characters 
from six different character sets. The contents of each of the 
character sets is described in Figure 1. 
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Figure 1. Character Sets and Their Contents 



How to Write User-Defined Commands 



You can update existing commands and create your own commands using the 
CHS EXEC command and the LOAD and GENMOD commands. 



EXEC COMMANDS 



The EXEC command allows you to create an EXEC procedure that has the 
effect of a command and which can be invoked by its filename, just as a 
command is invoked. EXEC procedures can contain CP, CHS, and 
user-defined commands and provide a convenient way of generating a 
predefined seguence of commands. You are implicitly specifying the EXEC 
command when you issue the filename of the EXEC procedure. 

There is one case when you must specify the EXEC command and its 
associated filename explicitly: when an EXEC is nested within another 
EXEC, the nested EXEC must be specified explicitly. 

Certain EXEC control statements let you conditionally execute 
statements within the procedure. You conditionally execute statements by 
means of the SIF, SLOOP, and &G0T0 statements, similar to the 
conditional and looping facilities found in high level languages. 



You can find all the information you need to write 
the ¥M^370: EXEC User's Guide. 



EXEC commands in 



A special type of EXEC procedure called a PROFILE EXEC can be used to 
set up a predetermined operating environment within CMS each time you 
use your virtual machine. If you have a PROFILE EXEC it is executed 
before the first command after you IPL CMS. It defines the conditions 
you want while you are programming under CHS. For example, if you are an 
assembler language programmer, you need the CMS, TEXT, and OS macro 
libraries accessed while you are processing. In your PROFILE EXEC, then, 
you could issue a GLOBAL command to access these libraries automatically 
whenever you IPL the CHS operating system. 
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COMMANDS CHEATED BY LOAD AND 6ENM0D 

You can use the LOAD and GENMOD commands to create program modules. A 
module is a relocatable file whose external references have been 
resolved: that is, a module is a file that you can execute by invoking 
its filename. The module filename is, effectively, a CHS command you 
define for your own use. 

A source program must be assembled or compiled to produce an object 
file that has a filetype of TEXT. The LOAD command loads the object 
file into virtual storage in your virtual machine. When LOAD executes, 
all external references for the file are resolved. You then use GENMOD 
to create an absolute core-image of the file or files loaded in storage* 
Its filetype is alvays MODULE. This core-image copy may then be used as 
a CMS command by invoking its filename. 

If you are creating a module containing more than one TEXT file, you 
include the additional TEXT files vith the INCLUDE command, then issue 
the GENMOD. 

Truncating and Abbreviating Commands 

To make the entering of commands on the keyboard more convenient, CP and 

CMS allow many commands (as well as many operands and options) to be 

used in a shortened form. The shortened form can be either an 

abbreviation or a truncation to its minimum form. Minimum truncations 

are shown within the format box and abbreviations are shown with the 

description that follows the format box for all the command formats in 
Part 2. 

In those formats, the minimum truncation is shown in uppercase 
letters in the command format box; the optional letters are shown in 
lowercase. This rule holds for options and operands as well. A good 
example of command truncation is the EDIT command. The format shows the 
command ftame as "Edit". This means you can enter the EDIT command in 
any of the following forms: 

EDIT 

ovx 

ED 

E 

E is the minimum truncation, but CHS accepts all of the above forms 
for the command. 

Abbreviations are shorter forms of commands and operands. 
Abbreviations for commands are shown below the full name of the command 
in the format box. Abbreviations for operands and options are shown in 
the description of the individual operands and options that follow the 
format box. For example, the operand READER has both a minimum 
truncation and an abbreviation. In the format box, it is shown as: 

Reader 

indicating the minimum truncation is R. In the discussion of the reader 
operand that follows, it is shown as: 

READER 
RDR 

indicating that the abbreviation is RDR. 
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Synonyms for CMS Commands 

Using the EDIT command, you can create a table of synonyms for both CMS 
commands and commands you define yourself. You create the file using 
the EDIT command in the form 

EDIT filename SYNONYM 

(the filetype must be SYNONYM) . You then enter the records that will be 
in the table, in the form 

commandname synonymname count 

where "commandname" is the name of the command for which you are 
creating a synonym, "synonymname" is the name of the synonym for the 
command name, and "count" is the number of characters you want to use as 
a minimum truncation value for the synonym. 

In order to use the synonym table once you have created it and filed 
it in your system, you must invoke the SYNONYM command at the beginning 
of every terminal session in which you want to use the table. 

You can find a more detailed explanation of how to use the SYNONYM 
command in Section 7. 



CMS Command Search Order 

You can create a user-defined command (that is, a module or EXEC 
procedure) which executes in your virtual machine and resides on disk. 
To execute such a command or EXEC procedure, you only have to enter the 
filename from the terminal. However, be aware of the CMS search order 
for terminal input. Once a match is found, the search stops. The 
search order is: 

1. EXEC file on any currently accessed disk. (The CMS RUN command is 
an EXEC file.) 

2. Valid abbreviation or truncation for an EXEC file on any currently 
accessed disk. 

3. Nucleus resident or transient area command. (The nucleus resident 
CHS commands are: CF, DEBUG, ERASE, GENMOD, INCLUDE, LOAD, LOADHOD, 
START, and STATE. The transient commands are: ACCESS, COHFARE, 
DISK, FILEDEF, GENDIRT, GLOBAL, LISTFILE, HODHAP, PRINT, PUNCH, 
QUERY, READCARD, RELEASE, RENAME, SET, SVCTRACE, SYNONYM, TAPE, and 
TYPE.) 

4. Command module on any currently accessed disk. (All the remaining 
CMS commands are disk resident and execute in the user area.) 

5. Valid abbreviation or truncation for nucleus-resident or transient 
area command module. 

6. Valid abbreviation or truncation for disk resident command. 

For example, if you create an EXEC file with the same name as a disk 
resident command, the CMS search always finds the EXEC file first. 
Thus, the disk resident command is never executed. 

Figure 2 shows more details of the command search order; you can find 
a complete description of the search order in the VM/370 : System 
Programmer's G uid e. 
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| Figure 2. How CHS Searches for the Command to Execute 
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INTERRUPTING THE EXECUTION OF A COMMAND 

You can suspend the execution of a command in your virtual machine using 
the Attention key (or its equivalent) on your terminal keyboard. 
Functionally, the Attention key requests the Control Program to 
interrupt the command currently executing, thus allowing you to key in 
new input. The interrupt takes effect immediately in most cases, but 
some commands complete execution before the interrupt takes effect. 

The name and physical location of the Attention key varies with 
different styles of terminals supported by VM/370. See the VM/370 : 
Terminal UserJ.s Guide for details on various styles of terminals. 



P.sin<j the Attention Key 

Using the Attention key, you can switch command environments (that is, 
switch from the CP to the VH command environment or vice versa) , at the 
same time you request an interrupt. What happens when you press the 
Attention key depends on two factors: the command environment of your 
virtual machine and the mode setting of your virtual console. 

Your virtual machine can be in one of two command environments: the 
CP command environment (CP) or the Virtual Machine command environment 
(VH) . These environments are defined by usage. Hhen you IPL an operating 
system for your virtual machine, your virtual machine is in the VM 
environment, otherwise, it is in the CP environment. 

You set the mode of your virtual console using the CP TERMINAL 
command. The MODE operand of this command allows you to set your virtual 
console in either the CP or VM mode. These modes correspond, in 
general, to the preceding command environments description. Each of the 
terminals that can be used with the VM/370 system has a key that is the 
equivalent of the Attention key on the 2741 (with which you signal an 
attention interrupt) . Unless otherwise noted, where the term "Attention 
key" is used in this publication, the phrase "(or equivalent)" is 
implied. The equivalent key on the 1050 terminal is the RESET LINE key; 
on the 3270 terminal, the Enter key. 

On a 3270 terminal you can signal an attention interrupt to the 
virtual machine with the ATTN or REQUEST commands. Issuing the ATTN or 
REQUEST commands on a 3270 is equivalent to pressing the Attention key 
once on a 2741. On a 3270 terminal, pressing the Enter key is equivalent 
to pressing the Attention key twice quickly on a 2741. 

For a 3215, you press the Attention key once to signal an attention 
interrupt to the virtual machine, then enter the #CP command to get to 
CP mode. 

How CP interprets attention interrupts issued by the virtual machine 
users depends on whether the terminal mode is set to CP or VM. 

The default mode setting for the primary system operator is: 

TERMINAL MODE CP 

If your default terminal mode is CP, or if you issued the above 
command, pressing the Attention key one or more times forces your 
virtual machine into CP mode. 
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I For all other users, the default mode setting is: 
| TERMINAL MODE VM 

I If the terminal mode is VH, pressing the Attention key once passes an 

I interrupt pending condition to the virtual machine operating system. 

I Pressing the Attention key twice guickly (or pressing the 3270's Enter 

I key) places your virtual machine in CP mode. 

| If you execute CHS from a 3270 device, you must issue the ATTN or 
( REQUEST command if you are in CP mode and want to return to the virtual 
| machine mode. 

The following two figures show the effect of an Attention interrupt 
when your virtual console is in either VH or CP mode. Figure 3 shows 
the action taken by VH/370 when your virtual console is in VH mode and 
you press the Attention key. The first column represents the condition 
of the terminal keyboard when you press the Attention key. The second 
column represents the number of times you press the Attention key. If 
your virtual console is in the VH mode, one Attention reguests an 
interrupt and two guick Attentions force your virtual machine to the CP 
command environment. The third column represents the action VH/370 
takes depending on the number of times you press the Attention key. 
"any" means that the effect of the Attention key is the same no matter 
| how many times you press it. 

I Hote; If the operator sets his terminal mode to VH and resets his 

| virtual machine, his console acts as described in the first state of 

| Figure 3 (that is, more than one attention is reguired to unlock the 

I keyboard for CP input) . 
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1 | Mo . | | 

j State of Terminal before | of | Resulting 1 
| Attention Key Pressed |ATTH| Action I 


| Terminal idle; keyboard | 1 (Attention interrupt pending; virtual | 
j locked; virtual machine j | machine running I 


I | >1 | Keyboard unlocked for CP input j 


| Terminal receiving output | 1 (Attention interrupt pending; virtual j 
I from virtual machine | | machine running I 


I | >1 | Keyboard unlocked for CP input at j 
| j | completion of console I/O j 


| Keyboard unlocked for input | 1 IDevice end (DE) and attention status | 
| to virtual machine; no | | pending; virtual machine running 1 | 


| deleted | >1 | Unit exception (OE) status pending; j 
| | | virtual machine running | 


I Keyboard unlocked for input | 1 | Unit exception (OE) status pending; I 
j to virtual machine; some | | virtual machine running j 


j | >1 IDevice end (DE) status pending; j 
| | | keyboard unlocked for CP input | 


| Keyboard locked; executing |any (Attention ignored I 
| CP command | I 


| Keyboard locked; in SLEEP |any | Keyboard unlocked for CP input | 
| mode entered via command | | I 


| Keyboard locked; in SLEEP I any | Virtual machine resumes execution | 
j mode entered via Diagnose! | I 
| instruction | | I 


| Terminal receiving output | 1 (Attention interrupt pending; virtual | 
| from CP but not from userj | machine running I 


I | >1 | Keyboard unlocked for CP input | 


| Terminal receiving output I any | Output line canceled and in some | 
| in response to CP command | | cases command output canceled | 


| Keyboard unlocked for CP I any (Attention interrupt made pending; I 
| input; no data entered or| | virtual machine running | 
I all data canceled | | I 


| Keyboard unlocked for CP I any | Input line canceled; keyboard | 
j input; some data entered | | unlocked for CP input | 


jiTo perform this function on a 3270, position the cursor one position j 
j to the left of the user input area (line 22, position 0) and press j 
I the Enter key. j 



Figure 3. Effects of Attention Interrupt While Virtual Console Is Set 
to the VM Terminal Mode 
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Figure 4 shows the action taken by VM/370 when your virtual console 
is in CP mode. If your virtual console is in CP mode and you press the 
Attention key one or more times, you force the virtual machine to the CP 
command environment. 



r ■■ ■■ "" 1 

| State of Terminal before | Resulting | 
| Attention key Pressed | Action | 


| Terminal idle; keyboard locked; | Keyboard unlocked for CP input j 
I virtual machine running j I 


| Terminal receiving output from | Keyboard unlocked for CP input | 
| virtual machine | 1 


| Keyboard unlocked for input to |Onit exception (OE) status pending; | 
| to virtual machine; no data j keyboard unlocked for CP input | 
| entered or all data deleted | I 


j Keyboard unlocked for input to IDevice end (DE) status pending; j 
| virtual machine; some data | keyboard unlocked for CP input | 
| entered j I 


| Keyboard locked; executing CP | Attention ignored j 
j command | I 


| Keyboard locked; in SLEEP mode (Keyboard unlocked for CP input j 
j entered via command | I 


| Keyboard locked; in SLEEP mode |Virtual machine resumes execution | 
j entered via Diagnose | j 
j instruction | I 


| Terminal receiving output from | Keyboard unlocked for CP input | 
| CP but not from user command | 1 


| Terminal receiving output in | Output line canceled and in some j 
j response to CP command | cases command output canceled j 


(Keyboard unlocked for CP input; (Attention interrupt made pending; j 
j no data entered or all data | virtual machine running ( 
| canceled | 1 


| Keyboard unlocked for CP input; |Input line canceled; keyboard ( 
| some data entered | unlocked for CP input | 

i , __ , .. ._,., — i 



Figure 4. Effects of Attention Interrupt While Virtual Console Is Set 
to the CP Terminal Mode 
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Section 3: CMS Virtual Disks and How To Use Them 



This section describes your virtual disk system and how you use it. It 
describes how the disks are named, how they are accessed, when they need 
to be formatted, how to access and release them and, in general, how to 
manipulate them. 

Your virtual machine can have many disks defined for it in the VH/370 
directory, but it can have at most ten virtual disks logically accessed 
at any time. Virtual disks are logical subdivisions of real disks; but 
they can be considered real disks. Each has its own virtual device 
address, virtual cylinders, and for CHS disks, a Master File Directory, 
which lists the files contained on the disk. 

You can reguest the operator to attach an entire real disk to your 
virtual machine. This real disk, once attached, is considered a virtual 
disk. 

Ihen your virtual machine is defined, the system programmer estimates 
your disk storage reguirements and allocates cylinders for your virtual 
disks accordingly. 



Virtual Disk Identifiers and Addresses 

Virtual disks have disk identifiers and virtual addresses. The virtual 
disk identifier (or filemode letter) is a single-letter specification, of 
A, B, C, D, E, F, G, S, Y, or Z. The disk identifier is a part of the 
filemode specification used in the CMS command line. The virtual disk 
address is a three-character hexadecimal number. The address can be 
assigned permanently in the VH/370 directory or temporarily via the CP 
DEFIHE command. 



THE A-DISK 

The A-disk is the primary user disk. It is a read/write disk which is 
accessed when you begin your CHS terminal session. You can create, 
store, and modify files using this disk. Usually, the address of the 
A-disk is 191. 



DISKS B THROUGH G, Y, AHD Z 

You may have several disks defined in your VH/370 directory entry. 
During a terminal session you may want to make these disks a part of 
your active virtual machine. In this case, you use the ACCESS command to 
acguire a disk and give it a name. The identifiers B through G, Y and Z 
are used to identify these disks. 

If you have a virtual 192 disk defined for your virtual machine in 
the VH/370 directory, or if you specifically define a virtual disk with 
address 192 before loading CHS, that disk is accessed as your D-disk at 
the time your A-disk is accessed. 
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THE S-DISK 

The S-disk is the system disk and is read-only. It contains the CMS 
nucleus and disk-resident command modules. The Y and Z disks can be 
extensions of the system disk, depending on your virtual machine 
configuration. If you have 190 and 19E disks defined in your VH/370 
directory entry, these are accessed as the s and I disks after you IPL 
CHS. 



Formatting Virtual Disks 

Before you use your virtual disks, you must ensure that they have been 
formatted. Each disk must be formatted the first time you use it; it 
need not be formatted thereafter. 

Use the CHS FORHAT command to format a virtual disk the first time 
you use it. However, the FORHAT command erases the contents of the disk, 
so you should take care not to issue FORHAT for a disk whose contents 
you want to save. 

Each time you use the CP DEFINE command to attach a temporary virtual 
disk to your virtual machine, you must issue the FORHAT command. 

If you are formatting a disk to contain OS or DOS files, use the 
IBCDASDI virtual disk initialization program, which is described in the 
VM/370; gperatorjs Guide. 



Virtual Disk Addresses and How They Are Defined 

Tou can have both permanent and temporary disks attached to your machine 
during a terminal session. Permanent disks are predefined in the VH/370 
directory entry for your virtual machine. Temporary disks are those you 
define for your own virtual machine using the CP DEFINE command. 



PERHANENT VIRTUAL DISKS 

The VH/370 directory entry for your virtual machine defines the 
permanent virtual disks. Each disk has associated with it an access mode 
specifying whether you can read or write on the disk or only read from 
it. The virtual disk entries in the VM/370 directory may typically look 
like the following: 

000 050 CHS 190 R 
010 005 CHS001 R 
050 005 CHS192 W 

The first two fields describe the device, virtual disk in this 
example, and the virtual address of the device. The third field 
specifies the device type of your virtual disk. The fourth and fifth 
fields specify the starting real cylinder at which your virtual disk 
logically begins and the number of cylinders allocated to your virtual 
disk, respectively. The sixth field is the label of the real disk on 
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HDISK 


197 


2314 


HDISK 


198 


3330 


HDISK 


194 


3330 



which the virtual disk is defined and the seventh field is a letter 
specifying the read/write mode of the disk. The HDISK control statement 
of the Directory Service Program is described in the VH/370 : Operator's 
Guide . 

Even though these devices are permanently attached to your virtual 
machine, you must access them using the CHS ACCESS command before you 
can use them. 



UfiJTlHlllb T IS Of UK A HI VXJ1XUA1. UXaAS 

Using the CP DEFINE command, you can attach a temporary disk to your 
virtual machine for the duration of a terminal session. Once attached, 
the disk must be accessed using the CHS ACCESS command. For example, the 
commands below allow you to use a temporary G-disk. 

| define t3330 as 291 cyl 10 

| Tou should then format it using the CHS FORHAT command: 

| format 291 g 

| Tou should respond to the CHS response messages. 



Accessing and Releasing Virtual Disks 

Even though virtual disks may be defined in the VH/370 directory entry 
for your virtual machine, you cannot use them until you access them. 
There may be many disks defined in that entry, but your CHS virtual 
machine may have access to only ten of them at a time. The CHS ACCESS 
command allows you to logically access a virtual disk for your CHS 
virtual machine. 

Since you can have only ten virtual disks active in your CHS machine 
at a time, you may want to release a disk so that you can access 
another. Tou use the CHS RELEASE command to logically release the 
virtual disk from your CHS virtual machine, then access the new disk 
using the ACCESS command. 



Linking to Another User's Virtual Disk 

VH/370 lets you link to a virtual disk owned by another user. Use the CP 
LINK command as shown in the example below: 

link to bensid 193 as 194 r pass= go 

This command links another user's virtual disk (whose address is 193) to 
your virtual machine, where it has the address 194. The R specifies that 
the disk can only be read and GO is the read password. BEHSID is the 
userid for the virtual machine to which you are linking. 

Tou may also have another user's virtual disk defined in your VH/370 
directory entry. 

Once you have linked a disk to your virtual machine, use the CHS 
ACCESS command to access it and give it a name. 
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Extending One Virtual Disk from Another 

Using the CMS ACCESS command, you can make one virtual disk a read-only 
extension of another so that when you specify that a disk is to be read, 
any extension to that disk is read also. For example, the command: 

access 192 d/a 

makes the D-disk an extension of the A-disk. 

When one virtual disk is an extension of another, the extension disk 
is, by definition, a read-only disk. However, you can respecify its 
access status by issuing the ACCESS again, this time not extending the 
D-disk from the A-disk. 

access 192 d 

Not only does extending one disk from another alter its access status, 
it may also affect the search order for the disk accessed on your 
system. 

When you issue a CHS command and specify * as the filemode, the 
extensions set via the ACCESS command are not in effect, that is, the 
search is in alphabetical order. 

Only one level of disk extension is permitted. 



Virtual Disk Search Order 

When you specify a file to be acted upon in a CHS command, the default 
(or standard) CHS search for that file is in alphabetical order; the 
A-disk first, B second, and so on. The standard search order is used 
when no mode letter is specified or implied. If a mode letter is 
specified or implied, the search order is first the given disk and then 
all the disks that are read-only extensions of the given disk (except 
for certain commands, such as LISTFILE and TAPE DUHP, which purposely 
ignore read-only extensions) . 



Read/Write Status of Virtual Disks: RIO and R/W 

The read/write status for a virtual disk defines whether you can read or 
read and write on a disk on your virtual machine. Tou can access disks 
in two ways: read-only, where files on that disk can only be read; and 
read/write, where files can be read and written. 

To access a disk, you must: 

1. Identify a disk as part of your virtual machine configuration. If 
the disk appears in your VH/370 directory entry it is already a 
part of your virtual machine configuration. Also, you can make a 
disk part of your configuration by issuing a CF LINK or DEFINE 
command. 

2. Identify the disk to CHS and assign it a file directory name. Tou 
issue the ACCESS command after you load CHS to do this. The CHS 
ACCESS command associates a particular disk with a given file 
directory name and, optionally, specifies which files on the disk 
are to be used and specifies the disk as read-only. 
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The following example shows how you add a temporary disk and a user 
disk to your CHS virtual machine. 

ipl cms 

link dept637 230 197 r 12601 

define t3330 as 192 cyl 5 

format 192 d 

access 197 b 

First the LIHK command adds a device at virtual address 197 to your 
virtual machine. (The disk added is defined in the VH/370 directory for 
a virtual machine with a userid of 0EPT637 as device address 230 with a 
read password of 12601.) 

Then the DEFINE command adds temporary disk space (from a CP pool of 
such space) to your virtual machine at address 192. 

The CHS FORHAT command initializes the temporary disk area (192) in 
the CHS format. 

The ACCESS command activates the disk at virtual address 197 (similar 
to VARY ONLINE in OS) and assigns the disk the file directory name B. 
The importance of the directory name was explained in the preceding 
section "Virtual Disk search Order" 

If ACCESS is not the first command entered after CHS is loaded, an 
automatic ACCESS is performed to access a disk at device address 191 as 
the A-disk. 

Both CP and CHS can control read/write access to disks, as is 
illustrated in Figure 5. 



CHS ACCESS 



CP 



ACCESS 



| Read— 
| only 



| Read/ 
I write 



Read-only 
Read/Write 



| Read-only | Read-only 
I Read-only | Read/Write 



Figure 5. CP and CHS Disk Access 



Access allowed by CP is determined by the VH/370 directory entry or 
the form of LIHK issued by a virtual machine operator for a particular 
disk. 

The read/write status of virtual disks can be controlled in several 
ways: 

• It can be specified explicitly in the VH/370 directory. 

• It can be specified by the CP DEFIHE command. 

• A disk can be made read-only by extending it from another disk. 

If the read/write status is defined in the VH/370 directory, it is 
either a read/write (R/W) or read-only (R/0) disk. R/W disks can be read 
from and written on; R/0 disks only may be read. 
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When you define a temporary disk at your terminal, that disk is 
always a R/s disk. 

The read/write status of a particular disk affects the way you use 
it. R/0 disks cannot be written on. For example, you cannot use a R/0 
disk to contain the output of a language processor. 

You can find the read/write status of a file by issuing the QUERY 
command with the DISK option. 
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Section 4: The CMS File System 



The file is the essential unit of data in the CMS system. A CMS file is 
a logically grouped unit of data you define via a CMS command. This 
section gives you information on how you can create a file and name it, 

| how files are used in the system, and how CMS handles OS data sets and 

| DOS files. 



Creating or Defining Files 

You can create a file using the CMS Editor, which is invoked with the 
CMS EDIT command. The Editor lets you create and modify a file on your 
virtual disk. The FILEDEF command defines data sets created under an OS 
system such as 0S/VS1 or 0S/VS2 so that they can be recognized by CMS. 
You use OS macros to perform I/O operations for these data sets. 

The files (or data sets) defined by FILEDEF can be OS data sets 
created by an OS system, DOS files created by a DOS system, or files 
created under CMS using OS macros simulated by CMS and residing on a CMS 
virtual disk. You can then access them under CMS just as you do files 
you create using the Editor. Files may also be introduced to the system 
by means of the EEADCARD, DISK, and TAPE commands. 

All the information you need to create a CMS file using the Editor 
can be found in the VM/370: EDIT Guide. The FILEDEF command is 
described later in this section and in Section 7. 

In order to create a file, you must define a name for the file and 
decide upon the filetype of the file; use of the file determines its 
filetype. This information is entered along with the command in the form 
of a file identifier. Appendix F lists the reserved filetypes and 
describes the use of each. 

For a description of how to load existing source card decks into your 
virtual machine, see the CMS BEAECARD command description. 



Naming Your Files: The File Identifier 

When you create a file in CMS, you name it using a file identifier. The 
file identifier consists of three fields: the filename (fn) , the 
filetype (ft) , and the f ilemode (fm) . This file identifier is then used 
to refer to the file while you are using CMS. 



THE FILENAME FIELD 

The filename for a file is a one- to eight-character alphameric symbol. 
The characters can be A through Z, a through z, through 9, and the 
special characters $, #, or a. You should be careful when using the # 
and 9 characters, since they are used also as VM/370 logical editing 
characters. 
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You can use any filename you wish: however, you should avoid 
duplicating naies or abbreviations for CP or CHS system commands. If 
you duplicate the name of a system command and invoke the name from CBS, 
the execution of that file depends on the CHS command search order, 
which is described in Section 2 under M CHS Command Search Order. n 

Filenames, in some cases, become user-defined command names. The 
filenames for files with the filetype HODOLE or EXEC have the same 
effect as a command, in many cases. 



THE FILETYPE FIELD 

The filetype is also a one- to eight-character alphameric symbol. The 
characters can be A through Z, a through z, through 9,' and the special 
characters $, #, or a. You can find more information about the filetype 
specification in the sections that follow. 

Certain filetypes have special meaning to CHS, that is, CHS assumes 
the file has specific characteristics such as record length, tab 
settings, truncation column, upper or lowercase, and other information 
of significance for use by a command. These special filetypes are 
described in a later section "CHS Filetypes" and are summarized in 
Appendix F. 



THE FILEHODE FIELD 

The filemode field has two characters: the filemode letter and the 
filemode number. The filemode letter is established by the ACCESS 
command, and specifies the virtual disk on which a file resides: A 
through G, S, Y, or Z. The filemode number can be a number from 0-5. 
Figure 6 shows what each filemode number means. The first column is the 
filemode number, the second column specifies the read/write status 
associated with the number, and the third column gives a brief 
description of how to use the filemode number. 
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I ■ - ■ 
I Filemode 
| Number 


Read/Write 
| Status 


— ■■■ - -■ --' ■■ ■'- ■ -i 

Meaning | 


i o 


! R/W 


The file specified is a private file; you \ 
cannot access a file with the filemode | 
unless you have read/write privileges for | 
the virtual disk on which the file resides.! 


| 1 


R/W 


You can read from and write into this file,| 
depending on how the disk is accessed. | 


I 2 


I R/W 


You can read from and write into this file, | 
depending on how the disk is accessed. j 
Certain files on the S-disk are mode 2; | 
you can access these files. You can also | 
use mode 2 to describe files on disks | 
other than the system disk. | 


I 3 


R/E 


The file is to be erased after it is read. | 
Usually, this filemode is used for | 
temporary work files created by the | 
language processors and some CHS commands. | 


I 4 


OS 


This file is created using OS macros. It | 
may be blocked and, if in OS variable | 
format, may contain Block Descriptor Words | 
(BDWs) and Record Descriptor Words (RDWs) . | 


I 5 


R/W 


Has the same meaning as filemode 1. j 


I 6-9 




Reserved for IBH use. I 



Figure 6. Determining Filemode Numbers 



The other information you need when using this field of the file 
identifier is found later in this section, "How to Specify the Filemode 
Field." 



CMS Filetypes 



The filetype field specifies the type of the file; that is, how the file 
functions in the CMS system. The filetype field is used by the EDIT 
command to define standards for record length, tab settings, upper or 
lowercase, truncation column, and so on. For other commands, the 
filetype field is used to identify a subset of all files that are 
appropriate for processing by that command, for example you may want to 
process all files with the filetype ASSEMBLE. 

Source files have a filetype describing the language in which the 
file is written; files containing relocatable object code have the 
filetype TEXT; files containing executable object code have the filetype 
MODULE; files containing listings have the filetype LISTING, and so on. 

The filetypes described in this section are reserved; that is, they 
have a special meaning to CMS when you specify them in the filetype 
field of the file identifier. They are most useful in the programming 
environment (for example, filetypes describing source files, EXEC, TEXT, 
MODULE, and LISTING files). There is also a description of files 
created during certain types of processing under CMS. 
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FILETYPES FOR ASSEMBLER AND COMPILER SOURCE FILES 

When you create a source file using the Editor you assign a filetype 
that describes the source language used to create the file. For example, 
when you create an assembler language file using the CMS Editor, the 
command you issue might be: 

edit myfile assemble 

where MYFILE is the filename of the file and ASSEMBLE is its filetype. 
When you specify the filetype as ASSEMBLE, you are telling the Editor 
that the file is an assembler language file, and that the records 
created should be appropriate for processing by the system assembler. 
The Editor uses the filetype ASSEMBLE to define suitable conditions for 
creation of an assembler language source file. That is, the Editor 
creates a file consisting of fixed-length, 80-character records, with 
all input translated to uppercase, and with standard tab settings of 1, 
10, 16, 31, 36, and so on. 

See "Appendix F. Reserved Filetype Descriptions" for a list of the 
filetypes associated with the other supported programming languages and 
the CMS commands. When you create source files, there are rules 
concerning usage of the file, the command you use to process the file 
under CMS, the record format of the file and the contents of the file. 



OBJECT FILES: FILETYPE TEXT 

When you execute one of the language processors, the results of the 
processing (assembled or compiled object code) are placed in a file with 
the same filename as the source file for the program, but with a 
filetype of TEXT. 

FILES WITH THE FILETYPE LISTING 

Also, when you execute the language processors, a listing describing the 
source code and the results of execution is contained in a file with the 
same filename as the source file and filetype LISTING. 



FILES WITH THE FILETYPES EXEC AND MODULE 

There are two types of files that can be executed by invoking the 
filename of the file. These two types of files are files that have 
either the filetype EXEC or the filetype MODULE. 

An EXEC file may be a procedure (a sequence of predefined commands to 
be executed as a unit) . EXEC procedures also provide you with a 
conditional execution capability similar to the looping facilities of 
high level languages. You can find information about how to write and 
use EXEC procedures in the VM/370: EXEC User's Guide. 

| In CMS, a MODULE file is a non-relocatable copy of a program or 
| routine that resides in storage in executable form. A MODULE file is 
created by loading an object file (filetype TEXT) in your virtual 
machine (via the LOAD command) and then generating the module via the 
GENHOD command. Like the EXEC file, the MODULE file can be executed by 
invoking its filename. 
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FILE GROUPS CREATED BY THE LANGUAGE PROCESSORS 

Many CHS commands create groupings of files, each related to the other 
by the same filename. Some of these files are permanent and some are 
temporary. For example, if you issue the command 

assemble myfile 

the system assembler executes to assemble the file named MYFILE. 
Execution of the assembler generates several files, some permanent and 
some temporary. You can reguest CMS to Ixst the permanent files by 
means of the LISTFILE command: 

listfile myfile * a1 

CHS then generates a list of all files with the filename of MYFILE, 
including the permanent files created during the execution of the 
assembler, which might look like this: 

MYFILE ASSEMBLE A1 
MYFILE TEXT A1 
MYFILE LISTING A1 

where the TEXT file contains the object code resulting from the 
assembly, and the LISTING file contains the program listing generated by 
the assembly. The source input file, MYFILE ASSEMBLE A1, is not 
erased. 

Temporary files are also created by the assembler for use as 
workfiles: 

MYFILE SYSUT1 
MYFILE SYSUT2 
MYFILE SYSUT3 

The filetypes of the workfiles may vary depending on the processor 
you are using. Disk space is allocated for the assembler work areas on 
an as-needed basis. They are erased when processing is complete. 

You should ensure that a file created during the execution of a 
language processor does not have the same file identifier as one you 
wish to save. CMS, when instructed by a language processor to write a 
file, erases any file with the same file identifier as the one 
specified. 



Using OS Programs and Macros under CMS 

You can assemble and execute programs under CMS that require the use of 
OS macros simulated by CMS. Figure 7 lists the OS macros that CHS 
simulates. 
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SVC 


I Macro 


Number 


| XDAP 


00 


| WAIT 


01 


| POST 


02 


| GETMAIN 


04 


| FBEEMAIN 


05 


| GETPOOL 


— 


| FREEPOOL 


— 


| LINK 


06 


| XCTL 


07 


| LOAD 


08 


| DELETE 


09 


| GETHAIN/ 


10 


| FBEEMAIN 




| TIME 


11 


i ABEND 


13 


| SPIE 


14 


| BLDL/FIND 


18 


| OPEN 


19 


| CLOSE 


20 


| STOW 


21 


| OPENJ 


22 


| TCLOSE 


23 


| DEVTYPE 


24 


| TBKBAL 


25 


| WTO/WTOB 


35 


| EXTBACT 


40 


| IDENTIFY 


41 


| ATTACH 


42 


| CHAP 


44 


| TTIMER 


46 


| STIHEB 


47 


| DEQ 


48 


| SNAP 


51 


1 ENQ 


56 


| FBEEDBUF 


57 


| STAE 


60 


| DETACH 


62 


| CHKPT 


63 


| BDJFCB 


64 


| SYNAD 


68 


| BSP 


69 


| GET/POT 


— 


| BEAD/HBITE 


— 


| NOTE/POINT 


— 


| CHECK 


— 


| TGET/TPOT 


93 


| TCLEABQ 


94 


| STAX 


96 


| BETDBN 

• 


" 


Figure 7. OS 


Macros Sii 



Function 
Bead or write direct access volumes 
Wait for an I/O completion 
Post the I/O completion 
Conditionally acguire user storage 
Belease user— acguired storage 
Simulate as SVC 10 
Simulate as SVC 10 
Link control to another phase 
Delete, then link control to another 

load phase 
Bead a phase into storage 
Delete a loaded phase 
Manipulate user free storage 

Get the time of day 

Terminate processing 

Allow processing program to 

handle program interrupts 
Manipulate simulated partitioned 

data files 
Activate a data file 
Deactivate a data file 
Manipulate partitioned directories 
Activate a data file 
Temporarily deactivate a data file 
Obtain device-type physical 

characteristics 
NOP 

Communicate with the terminal 
Effective NOP 
Add entry to loader table 
Effective LINK 
Effective NOP 
Access or cancel timer 
Set timer 
Effective NOP 

Dump specified areas of storage 
Bffective NOP 

Belease a free storage buffer 
Allow processing program to 

decipher ABEND conditions 
Effective NOP 
Effective NOP 
Obtain information from FILEDEF 

command 
Handle data set error conditions 
Backup a record on a tape or disk 
Access system— blocked data 
Access system-record data 
Manage data set positioning 
Verify BEAD/WBITE completion 
Bead or write a terminal line 
Clear terminal input queue 
Create an attention exit block 
Return from a linked or 

attached routine 
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ASSEMBLING A PROGRAM USING OS MACROS 

To assemble a program that uses OS macros, you must first issue a GLOBAL 
command to make the macro library containing the macros available to the 
assembler. 

global maclib osmacro 

Once you have accessed the macro library, you can use macros from the 
library to assemble a program like the one shown in the following 
e samp j. g i 

TESTER CSECT 



OPEN (OOTDCB, (OUTPUT)) 



PUT OUTDCB,AREA 



CLOSE OUTDCB 

* 

OUTDCB DCB DDNAHE=OUT, ... 

To assemble the example, issue the command: 

assemble tester 

After the file is assembled, you can load the resulting TEXT file and 
then execute the program. 

EXECUTING A PROGRAM THAT USES OS MACROS 

In order to execute a program that uses OS macros, you must associate 
each DCB statement in your program with the device specified to perform 
the input/output operation for it. As in OS, this association is made 
via the ddname. In CHS, however, you issue the FILEDEF command, which 
performs a function for CHS that parallels the function performed by the 
DD statement in OS. 

Thus, to execute the preceding example program, you issue these 
commands: 

filedef out disk tester output a1 

load tester 

start 

When you use the OS macros simulated by CMS to read and write (as in 
the example) , you can write only to CHS disks. You cannot issue a write 
| to an OS or DOS disk. Also, CHS does not simulate all reads and writes; 
only the OS BSAH, BPAH, QSAH, and BDAH access methods are simulated. 

Files written on a CHS disk can, in turn, be read by programs running 
under CHS when those programs reguest that CHS simulate a read (for 
instance a GET or READ macro) . 
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I BEADIHG OS DATA SETS FBOH OS DISKS AND DOS FILES FROM DOS DISKS 



Sequential and partitioned data sets residing on OS disks, and 
sequential files residing on DOS disks, can be read by programs using OS 
■acros running under CHS. Also, certain CHS comaands can be used to 
process these data sets and files on OS and DOS disks. Figure 8 lists 
commands you can use to Manipulate OS data sets and DOS files under CHS, 
and briefly describes the function of the command in relation to its use 
with OS data sets and DOS files. 



Command 



Operation 



ACCESS | Hakes the OS or DOS disk containing the OS data set or DOS 
file available in B/0 status to your CHS virtual machine. 

RELEASE | Releases the OS or DOS disk you have accessed (via ACCESS) 
from your CHS virtual machine. 

LISTDS | Lists information describing OS data sets residing on an 
OS disk, or DOS files on a DOS disk. 

STATE I Verifies the existence of an OS data set or DOS file on a 
disk. Before STATE can verify the existence of the data 
set or file, you must have defined it (via FILEDEF) . 

FILEDEF I Defines the OS data set or DOS file for use under CHS by 

associating an OS ddname vith an OS data set name or DOS 
file-id. Once defined by FILEDEF, the OS data set or DOS 
file can be used by an OS program running under CHS and 
can be manipulated by the other commands that support OS 
functions. 

DDR I Copies an entire OS or DOS disk to tape. 

GLOBAL I Hakes macro libraries available to the assembler. You can 
prepare an OS macro library for reference by the GLOBAL 
command by issuing FILEDEF for the data set and giving 
the data set a filetype of HACLIB. 

Bote: If you are going to assemble, remember that the 
ddname to use on the FILEDEF command must be CHSLIB. 

ASSEMBLE I Assembles an OS data set or DOS file under CHS. 

HOVEFILEI Hoves data records from one device to another device. Each 
device is specified by a ddname, which must have been 
defined via FILEDEF. 

QUEBY | Lists (1) the status of virtual machine features specified 
by the CHS SET command, (2) the files that have been 
defined via FILEDEF in your system of virtual disks, and 
(3) the status of virtual disks attached to your virtual 
machine. 

| Figure 8. CHS Commands Used in Processing Data Sets on OS Disks and Files 
| on DOS Disks 
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Restrictions for Reading OS Data Sets 

The following restrictions apply when you read OS data sets under CMS: 

• Read password-protected data sets are not read. 

• VSAM, BDAM, and ISAM data sets are not read. 

• Multi volume data sets are read as single-volume data sets. 
End-of-volume is treated as end-of-file and there is no end-of-volume 
switching. 

• Keys in data sets with keys are ignored; only the data is read. 

• User labels in user-labeled data sets are bypassed. 

Restrictions for Reading DOS Files 

The following restrictions apply when you read DOS files under CMS: 

• Mo DOS macros are simulated. 

• Only DOS seguential files can be read. CHS operands and options that 
do not apply to OS seguential data sets (such as the MEMBER and 
CONCAT options of FILEDEF and the PDS option of MOVEFILE) also do not 
apply to DOS seguential files. 

• The following types of DOS files cannot be read: 

-DOS VSAM, DAM and ISAM files. 

-DOS core image, relocatable, source statement and procedure 
libraries. 

-Files with the input security indicator on. 

-Files that contain more than 16 user label and/or data extents. (If 
the file has user labels, they occupy the first extent; therefore 
the file must contain no more than 15 data extents.) 

• Multivolume files are read as single-volume files. End-of-volume is 
treated as end-of-file. There is no end-of-volume switching. 

• user labels in user-labeled files are bypassed. 

• Since DOS files do not contain BLKSIZE, RECFH, or LRECL options, 
these options must be specified via the FILEDEF command or the DCB 
statement; otherwise, defaults of BLOCKSIZE=32760 and RECFM=U are 
assigned. LRECL is not used for RECFM=U files. 

• If a DOS file-id does not follow OS naming conventions (that is, one- 
to eight-byte gualifiers with each gualifier separated by a period; 
up to 44 characters including periods) , you must use the DSN ? 
operand of FILEDEF and the ? operand of LISTDS to enter the DOS 
file-id. 
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Using the FILEDEF and MOVEFILE Commands 



The following examples show how to use the FILEDEF and MOVEFILE commands 
to handle OS data sets and DOS files under CMS. 

The following seguence of CHS commands moves an OS STOW macro file 
from an OS partitioned data set called SYS1.HACLIB or a CHS file called 
SYS1 MACLIB to the CHS file STOW HACRO. 

access 195 b/a 

filedef testl disk sysl maclib b1 (member stow) 

filedef macro disk stow macro 

movefile testl macro 

The following seguence of CHS commands moves all the members of an OS 
partitioned data set called SYS1.HACLIB or a CHS file called SIS1 HACLIB 
into separate CHS files, each with a filename egual to its member name 
and a filetype of HACRO. 

access 195 b 

filedef test2 disk sysl maclib b1 

filedef macro disk 

movefile test2 macro (pds) 

Either of the following seguences of CHS commands can be used to 
verify the existence of the OS data set called TEST. OS.SAHPLE. 1 and 
assemble it with SYSL HACLIB on an OS disk and CHSLIB on a CHS disk. 

access 198 d 

listds test os sample 1 * 

filedef assemble d1 dsn test os sample 1 

filedef cmslib disk sysl maclib * (concat 

global maclib sysl cmslib 

assemble file 

— or — 

access 198 d 

filedef assemble disk testl assemble dl dsn ? 

test. os. sample. 1 

state testl assemble * 

filedef cmslib disk cmslib maclib * (block 3360 lrecl 80 recfm fb concat) 

filedef cmslib disk sysl maclib * (concat) 

global maclib cmslib sysl 

assemble testl 

The following seguence of CHS commands moves a DOS file named DAILY 
ACCOUNT JAN 1 from the DOS 195 disk to the CMS file FILE OUT. 

access 195 b 

filedef in disk file in b1 dsn ? 

DMSFLD220R ENTER DATA SET NAME 

daily account jan 1 

movefile in out 

(A default FILEDEF is issued for FILE OUT.) 
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USING PROGRAM PRODUCTS UNDER CMS 

The CMS assembler and the Program Product language processors supported 
by CMS (listed in the VM/370: Introduction) are OS programs that reguire 
definition via FILEDEF in order to perform input/output processing. For 
input, all of these programs can use seguential or partitioned data sets 
that reside on OS disks, or seguential files that reside on DOS disks. 

When a supported language processor is executed under CMS, CMS issues 
FILEDEFs for the data sets or files it reguires in order to execute the 
program. You can override these default definitions by issuing a 
FILEDEF for those data sets or files before you invoke the language 
processor. You must issue the FILEDEF for the data set or file each 
time you want to use it, since the processors clear all file definitions 
when they complete their processing. 

When OS compilers execute under CMS, they normally: 

• Run the compilation to completion. 

• Display any diagnostics at the terminal. 

• Generate a CMS disk file with the same filename as the source program 
and a filetype of TEXT, which contains the object deck created by the 
assembler or compiler. 

• Direct the printed output of the assembler or compiler to the spooled 
printer or to a disk file with a filetype of LISTING. 

The filename of files created by the assembler or compilers running 
under CMS is egual to that of the source file. 

Disk work files reguired by the assembler or OS compilers under CMS 
are automatically created during compilation and erased at the end of 
compilation. No cataloging or erasing of data sets is reguired. 

Object programs (TEXT files) produced under CMS and under OS in real 
or virtual machines may be executed under CMS if they do not utilize 
certain OS functions not simulated by CMS. (OS macro functions that are 
simulated are discussed in "Using OS Programs and Macros under CMS.") 

| Object programs (except for the PL/I Checker) using non-simulated OS 
macro functions must be transferred to an appropriate real or virtual OS 

| machine for execution. PL/I Checker programs that use non-simulated OS 

| macro functions must be both assembled and executed on the appropriate 

| real or virtual OS machine. 



How to Specify the Filemode Field 

The filemode field of the file identifier is comprised of two 
characters: a virtual disk letter and a filemode number. In almost all 
CMS commands, this field is optional. You need not specify it since CMS 
itself has the ability to search for the file. Some commands, in fact, 
do not permit a filemode entry. 

There are four ways to specify this field of the file identifier: 

• Explicitly, by actually entering the filemode letter and filemode 
number in the filemode field. 

• Implicitly, by leaving the entire field blank. 
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• By specifying an asterisk (*) in the filemode field. 

• By specifying an egual sign (=) in the filemode field. 

If you specify the filemode explicitly, the virtual disk you specify 
and any extensions of it are searched for your file. If, however, the 
virtual disk you specify is an extension, the extension disk is 
searched, but not the parent disk. If you specify a read-only virtual 
disk when you are writing a file, CMS returns an error message. 

If you specify the filemode field implicitly by leaving it blank, 
only your A disk and its extensions are searched for the file. 

The asterisk (*) can have two meanings, depending on the command with 
which it is specified: (1) search all disks until the specified file is 
found, or (2) search all disks for all occurrences of the file. 

The egual sign (=) as the filemode is specified when you want to read 
from and write on the same virtual disk. This character can be used 
only on disks for which you have read/write privileges. 

When you are using one of the Program Product language processors to 
write to a virtual disk, CMS first attempts to write to the virtual disk 
you specify and then attempts to write to that disk's parent (if one 
exists) . If there is no room on either of these disks, or if both disks 
are read-only, writing is done only to the A-disk. 

SPECIFYING SEARCH ORDER USING THE FILEMODE FIELD 

A CMS function that is trying to locate a file on a disk may search for 
that file in either of two ways: 

• If it is searching for a file with a particular filemode, such as 
"A", that disk and its immediate extensions are searched. 

• If it is to search all accessed disks (Filemode *) , the disks are 
searched in alphabetical order (ABCDEFGSYZ). 

CMS functions or commands that do not allow you to specify the 
filemode (such as LOAD, ASSEMBLE, and MACLIB) use the second type of 
search, and search all accessed disks in alphabetical order. 

Commands that allow you to specify the filemode may do either type of 
search. If you specify a particular disk or allow it to default to "A", 
then the first type of search is done. If you specify filemode as '•*", 
then the second type of search is done. 

However, the LISTFILE and TAPE DUMP commands do not use extensions in 
search of a particular disk. 



Libraries 

CMS provides two types of libraries: macro libraries and text, or 
program libraries. A library is a file with the filetype MACLIB or 
TXTLIB. Unlike other CMS files, a library file consists of members plus 
a dictionary for locating the members by name within the library file. 
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A macro library is a file whose filetype is MACLIB. It contains a 
dictionary and members which are macro definitions. The system macro 
libraries are CMSLIB MACLIB, OSMACRO MACLIB, OSMACR01 MACLIB and TSOMAC 
MACLIB. CMSLIB MACLIB contains the CMS macros. OSMACRO MACLIB contains 
selected OS macros from the OS macro library, SYS 1. MACLIB, which are 
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simulated by CMS. OSMACRO 1 MACLIB contains the other macros from 
SYS1.MACLIB, making it possible to assemble a program in CHS for OS 
execution. And, TSOMAC MACLIB contains selected TSO macros. 

You can create your own macro library by using the MACLIB command. 
Files with the filetype MACRO or COPY can be specified in the MACLIB 
command for inclusion in the library. The MACLIB command can also be 
used to add, delete, or replace macros in an existing library; to list 
the name, size, and location of macros in a library; and to compress a 
library. 

A text library is a file whose filetype is TXTLIB. It contains a 
dictionary and members that are relocatable text files. The system text 
library CHSLIB TXTLIB contains extended precision floating point 
simulation routines. If you are a TSO user, you can also access the 
TSOLIB TXTLIB. 

You can generate your own text library by using the TXTLIB command. 
Only files with the filetype TEXT may be included. A maximum of 1000 
control section names and entry points can be contained in a TXTLIB 
file. The TXTLIB command may also be used to add or delete members from 
a library or to list the entry points, control section names, and the 
location of members of the library. 

CMS has no automatic library calls. A library must be made available 
using the GLOBAL command before CMS will search it. GLOBAL has two 
forms, the TXTLIB form for specifying text libraries, and the MACLIB 
form for specifying macro libraries. The command GLOBAL MACLIB CMSLIB 
OSMACRO would make CMSLIB MACLIB and OSMACRO MACLIB available to be 
searched during an assembly for macro operation codes, and they would be 
searched in the order they were named in the GLOBAL command. Text 
libraries that are made available with the GLOBAL command are searched 
for missing subroutines or undefined filenames whenever the LOAD or 
INCLUDE commands are issued. Up to eight libraries may be specified 
with either form of GLOBAL. The commands GLOBAL TXTLIB and GLOBAL 
MACLIB, specifying no library names, terminate searching of previously 
specified libraries. 

Descriptions of the MACLIB, TXTLIB, and GLOBAL commands appear in 
Section 7. 



I CMS Tape Handling 

| CMS has two commands that handle tapes. 

| The CMS TAPE command dumps CMS formatted files from disk to tape, 
| loads such files from tape to disk, and performs various control 
| operations on a specific tape, such as setting tape modes, forward or 
| backward spacing, and rewinding the tape. The TAPE command is used 
j solely for CMS files. The files on tape are created in a unigue format 
| that can be read only by the TAPE LOAD command. 

I The TAPPDS command reads tapes created by the OS utility programs 
| such as IEHMOVE, IEBUPDTE, and IEBPTPCH. If the tape contains an OS 
| partitioned data set (PDS) produced by the OS IEBPTPCH utility, the 
| TAPPDS command can write the members as individual CHS files. 
| Optionally, it produces CMS files from tape in the OS IEBDPDTE control 
| file format, blocked or unblocked. TAPPDS can also create CMS files 
I from unloaded partitioned data sets in IEHMOVE format, blocked or 
| unblocked. The tape may be unlabeled or may have a standard OS label. 
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I Bote: The MOVEFILE and DDR commands, as well as user-written programs, 
| can handle tapes. 



I CMS Unit Record Support 

| CHS supports one virtual card reader at virtual address 00C, one virtual 
| card punch at virtual address 00D, and one virtual printer at virtual 
| address 00E. Under VH/370, these devices are spooled. CHS does not 
| support real or dedicated unit record devices, nor does it support a 
I virtual 2520 Card Punch. 



| CARD READER 



The READCARD command reads data records from the spooled card reader to 
a CHS disk. Input records of 151 or less characters are accepted. 
Column binary data is not acceptable. All user-generated card decks 
must be read into the virtual reader before a READCARD command can be 
issued. You can get card decks into a CHS reader in either of two ways: 

• A card deck, containing only one file, is placed in a real card 
reader and read by CP. The deck must be preceded by a VH/370 
identification (ID) card specifying the userid of the virtual machine 
to receive the card images. (Files must be read in separately, even 
if they are for the same virtual machine. If a second deck is placed 
behind the first, the second ID is ignored and the second file is 
treated as though it were part of the first file. The only 
end-of-file condition recognized is an end-of-file on the real 
device.) The card images are placed on a spool file in the specified 
virtual machine's virtual card reader. If the specified user is not 
logged on to the system, the deck remains in his virtual card reader 
until he logs on and issues the READCARD command. 

• One virtual machine transfers records from its virtual card punch or 
printer to a virtual card reader (its own or that of another user) . 
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Section 5: Writing and Executing a Sample Program Using CMS 



Once you have read the preceding four sections, you can use the sample 
program in this section as an introduction to the interactive facilities 
of VH/370. This section contains the information you need to create and 
use a program that runs under the CMS operating system. The text is 
organized so that you can enter the sample program at your terminal as 
you read. 

The sample program treats a number of VM/370 commands in a 
"one-situation" manner. That is, most of the commands can be used in 
ways other than that shown in the sample program. 

The first part of this section describes the steps you take before 
creating the program: learning to use your terminal, contacting the 
computer, loading the CMS operating system and formatting a disk with 
which to work. 

The second part of this section deals with two topics: how to use the 
CMS Editor to create a program and how to use VM/370 commands to execute 
it. 

The program you write is a simple one, even though it is coded in 
assembler language. It consists of only a few statements; all you need 
to do is enter them. When the program executes, you can use it 
interactively, so you get an idea of how to use VM/370 interactively. 



Getting Started 

VM/370 is an operating system that provides you with a unigue 
facility — your own machine. This machine is a virtual machine, that is, 
a machine with software counterparts for almost all of the hardware 
components of a real machine. All of these components are controlled 
from your terminal, which is your virtual console. 

On the real machine console, there are lights and keys that help you 
manipulate the machine; on the virtual console (your terminal) , you 
manipulate the machine using the command languages of the CP and CHS 
operating systems. 

The CP command language lets you manipulate your virtual machine 
components. For example, you could temporarily define a new device for 
your virtual machine using the CP DEFINE command. The CMS command 
language allows you to manipulate the virtual disks on your system and 
the files contained in them. For example, you can create and assemble a 
program file in assembler language using the CMS EDIT and ASSEMBLE 
commands. 



WHAT YOU SHOULD KNOW BEFORE YOU CAN USE CP AND CHS 

Before you can use CP and CMS, you should know (1) how to operate your 
terminal and (2) your userid (user identification) and password. 
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l^e Terminal; Your Virtual Console 

There are many types of terminals you can use as a VM/370 virtual 
console. Before you can conveniently use any of the commands and 
facilities described in this section, you have to familiarize yourself 
with the terminal you will be using. Generally, you can find 
information about the type of terminal you are using and how to use it 
| with VM/370 in the VM/370: Terminal User's Guide. If your terminal is a 
I 3767, you also need the IBM 3767 Operator's Guide. The sample program 
is designed for typewriter terminals. Where parallel commands are 
needed for display terminals, you can find these commands described in 
the VM/370: EDIT Guide. 



ISJiE Use rid and Password: Keys into the Sy_stem 

Your userid is a symbol that identifies your virtual machine to VM/370 
and allows you to access VM/370. Your password is a symbol that 
functions as a protective device ensuring that only those authorized to 
use your virtual machine can use it. Both symbols are usually defined 

by the system programmer for your installation and you can obtain them 
from him. 

Hhen you are familiar with your terminal and know your userid and 
password, you are nearly ready to use VM/370. But before you begin 
using your terminal to enter commands, you should know how the VM/370 
Logical Editing Characters can help you correct the typing mistakes you 
may make at your terminal. 



Correcting Data at Your Virtual Console 

VM/370 has a set of symbols you can use to correct typing errors and to 
change data as you enter lines at your keyboard. Using these logical 
editing symbols, you can cancel a line entirely, change a character in a 
line, logically end a line and begin a new one without pressing the 
Enter Key (or eguivalent) and ignore the special meaning of a character 
on a line. Figure 9 lists the default logical editing symbols. To 
change the symbols' use, you must either define different logical 
editing symbols in your VM/370 directory entry or issue the CP TERMINAL 
command. 



Symbol | Function 



3 | Logical Character Delete 

# | Logical Line End 

t | Logical Line Delete 

| Logical Escape 



ii 



Figure 9. Logical Editing Symbols 



When you enter your input lines using these symbols, you do not see 
the effect they have immediately, since VM/370 is simply accepting the 
input you are entering. You can see the effect the logical editing 
symbols have when you reguest VM/370 to show you your input file. 
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The Logical Character Delete Symbol (9) : Deletes the character preceding 
it on the input line. A string of character delete symbols deletes a 
corresponding number of preceding characters. For example, if you make 
a typing error such as: 

permnaent 

just enter five character delete symbols and follow them with the 
correct letters, as follows: 

permnaentaaaaaanent 

when you press the Enter Key on your terminal, the line is accepted by 
VM/370 

permanent 

The Logical Line Delete Symbol (£) : Causes your virtual machine to 
delete the logical line you are entering. For example, 

a formula of the highest affirmation 

causes the entire line to be ignored by VM/370. You can press the Enter 
key to continue typing, or you can continue on the same input. 

The Logical Line End Symbol (#) : Causes your virtual machine to 
logically end the line you are entering. This symbol allows you to 
enter many logical lines on one physical line, for example, 

a formula#of the highest#af firmation 

is accepted by VM/370 as 

a formula 

of the highest 

affirmation 

The Logical Escape Symbol (") : Tells your virtual machine to ignore the 
special line-editing meaning of the character that follows. You use the 
logical escape symbol to ignore the line-editing meaning of the special 
characters that you do not want VM/370 to misinterpret. For example, 
VM/370 misinterprets the following line: 

1 gross #2 pencils a 92* per dozen 

The special characters on this line are interpreted by VM/370 as: 

• Begin a new line after "gross" 

• Delete the blank space after "pencils" 

• Erase everything starting with the # sign through the t. 

However, the line is correctly interpreted if entered as follows: 
1 gross "#2 pencils "3 92"£ per dozen 
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Note: The user may not be able to predict the results of nixing three or 
more consecutive line editing symbols because of the way the input line 
is acted upon by VM/370. For example: 

abc""adef 

and 
abc"»aadef 

both result in 
abcdef 



CONTACTING VM/370 AND LOGGING ON 

The next steps to take before you begin to create the program are: (1) 
contacting VM/370 and (2) identifying yourself to the computer. 



Contacting VM/370 

To contact VM/370, you switch the terminal device on and VM/370 responds 
with the message: 

vm/370 online 

to let you know that VM/370 is running and that you can use it. If you 
do not receive the "vm/370 online" message, see the VM/370 : Terminal 
2§er^s Guide for help. You can now press the Attention key (or 
eguivalent) on your terminal and issue the LOGON command to identify 
yourself to the system: 

logon smith 

where SMITH is used as your userid. The LOGON command is entered by 
pressing the Return (or Enter) key. If VM/370 accepts your userid, it 
responds by asking you for your password: 

ENTER PASSWORD: 

You then enter your password, which is, in most installations, hidden by 
the system. 

The series of lines you and the computer have exchanged so far looks 
like this: 

vm/370 online When you switched your terminal on, VM/370 responded 

to let you know it was ready for your input. 

(Attgntion) You press the Attention key. 

logon smith You entered the LOGON command and your userid, and 

then pressed the Return key. 

ENTER PASSWORD: VM/370 asked you for your password in response. 

ZXXXXXX You entered your password and the system hides it. 

The logging on process is now complete and you can load your virtual 
machine with an operating system, such as the Conversational Monitor 
system (CMS) . 
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Lfi&DING QMC; JN THT? WTRTIIST. M1PHTN1?- THT? TDT CQMMSNT) 

The Conversational Monitor System is an interactive operating system 
designed for VM/370 virtual machines. CMS provides commands for 
manipulating virtual disks (virtual disks correspond to real disks on 
real machines) and files (units of data records such as programs or 
input data for programs) . You load CMS in your virtual machine using 
the CP IPL command: 

ipl cms 

where "cms" is assumed to be the saved system name for your 
installation's CMS. VM/370 responds by displaying a message such as: 

CMS VERSION v.l - mm/dd/yy 12:02 

to indicate that the IPL command executed successfully and that CMS is 
loaded. 
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l°£I.§tting Your Virtual Disk Storage Space 

If this is the first tine the virtual disk is used you should make sure 
that it is formatted. Be careful to use this information only if you 
know your disk must be formatted. Ask your system programmer whether or 
not you should format your virtual disk. FORMAT takes the form: 

format 191 a 

CHS then prompts you with the following message: 

DHSFOR603R FORMAT HILL ERASE ALL FILES OH DISK • A (191) • - DO YOU 
WISH TO COHTIHUE? (YES | HO): 

You answer: 

yes 

CMS then asks you for the disk label of the disk to be formatted, which 
you can get from the system programmer: 

DMSFOR605R EHTER DISK LABEL: 

You answer by entering a disk label: 

HYDISK 

CHS then erases all the files on that disk, if any existed, and formats 
the disk for your use. When you enter the label, CMS responds by telling 
you: 

FORMATTIHG DISK 'A 1 

•3» CYLIHDERS FORMATTED OH *A(191) f . 

R; T=0. 15/1.60 11:26:03 

You have to issue this command the first time you use the virtual disk. 



The CMS Read v. Hessaqe 

The last line of the response from CHS in the preceding example was a 
Ready message. All CHS commands generate a Ready message when they 
complete processing. The Ready message is a response from the system to 
let you know you can enter data into the system. The form of the Ready 
message can vary, since it can be changed using the SET command. The 
preceding example shows the long form of the Ready message. If your 
Ready message is set to a short form, VH/370 lets you know when you can 
enter another command by sending you a message that looks like: 

B; 

Until now, the commands discussed have had to do with the process of 
getting you situated on your virtual machine; you have learned to use 
the terminal, contacted VH/370, logged on, loaded an operating system, 
and formatted a disk to use. How you can go on to create a program, 
assemble, load, and execute it. 



Section 5: Writing and Executing a Sample Program Using CHS 51 



Using CMS to Create. Assemble, Load, and Execute a Program 

The following information is a description of the four steps in writing 
a program using CHS: (1) creating a program file, (2) assembling the 
source file, (3) correcting the file if there are errors in it, and (4) 
loading and executing the program. Before you can begin, however, you 
should know a little about the CHS Editor. 



HOW TO USE THE CHS EDITOB 

The CHS Editor is the programming tool you can use to create and modify 
your program. The information you are about to read tells you how to use 
the basic EDIT subcommands you need to create your program. 



Invoking the Editor; The EDIT Command 

The Editor is a CHS component designed to make it convenient to cteate 
and modify files using the CHS operating system. The Editor is invoked 
by the EDIT command, which, for your program, takes the form: 

edit sample assemble 

where SAHPLE is the name of the file you are creating, and ASSEHBLE is 
the filetype of the file. The filetype tells the Editor that the file 
you are creating is a file written in the assembler language. The 
Editor sets the correct logical tab settings you should use when 
entering the Assembler language statements. 

When you enter the preceding EDIT command line, CHS responds with the 
message 

HEW FILE: 
EDIT: 

You are now in the EDIT mode. 



The EDIT Command Hodes: EDIT and IHPDT 

The Editor can be used in two modes, EDIT mode and INPUT mode. The 
INPUT mode is used solely for entering new lines of data into your file. 
The EDIT mode is used to correct mistakes you made when you initially 
created the file or to modify the file. The EDIT command automatically 
places your virtual machine in the EDIT mode; you enter the EDIT 
subcommand IHPDT to place your virtual machine in the INPUT mode. To 
get out of INPUT mode, press the Return key (or eguivalent) on a null 
line, that is, press the Return key without entering any data. 

Usually, when you create a file, you first create the source records 
and then check them for errors. The Editor provides subcommands to make 
the creation and correction of files convenient. The two sections that 
follow describe (1) the subcommand you use when creating the file and 
(2) other EDIT subcommands that are useful to you in creating and 
correcting the program file. All of the facilities of the EDIT command 
are described in the VH/370: EDIT Guide. 
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The Current Line Pointer 

When you use the Editor, you change one line at a time. The Editor uses 
a "current line pointer" to point to, or show you, the current line in 
your file. If you enter the TYPE subcommand, the Editor displays the 
line it is currently pointing to without changing the pointer. 



CREATING YOUB SOURCE RECORDS: THE INPUT SUBCOMMAND 

You can use the INPUT subcommand in two ways: (1) to enter the INPUT 
mode or (2) to insert a single line of data into your file. To enter 
the INPUT mode, you enter the INPUT subcommand and press the Return key. 
To insert a single line of data, you enter the INPUT subcommand followed 
by the line of data, then press the Return key. 

When you are in the INPUT mode, the Editor accepts anything you enter 
on the command line, regardless of its internal system definition. Only 
the logical editing symbols can be used in the INPUT mode to change a 
line. All you can do in the INPUT mode is add new lines of data to your 
file. 

Usually the Editor is used to create new files and modify existing 
files, so it has features that make this convenient, such as line number 
prompting for some language processors and tab settings for all 
supported language processors. For the assembler language program you 
are creating, you can use tab settings provided by the Editor to space 
to the correct position for assembler language instruction fields. 



OTHER EDIT SUBCOMMANDS YOU NEED 

The EDIT subcommands described here are almost self-descriptive. They 
let you see what your file contains, alter its contents, and store it on 
disk. Remember that these are only a few of the Editor's facilities and 
that you can find the rest described in the VM^/370: EDIT Guide. 



To See the First or Last Record of Your File: Use the TOP and BOTTOM 
Subcommands 

To see the first record of your file, instruct the Editor to type the 
top record: 

top 

The top record of the file is always a null line, placed there by CMS 
so that you can always insert records at the beginning of your file. 
So, to see the first actual line of data, use the subcommand DOWN 1, 
which points the Editor to the line below the null line. 

To see the last record in your file, instruct the Editor to locate 
the bottom record of the file: 

bottom 
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To See Records Above or Below the Current Line: Use the UP and DOWN 
Subcommands 

To see records above the current line, instruct the Editor to move up in 
your file: 

up number 

where number is the number of lines above the active line. For example, 
UP 7 moves the current line pointer seven lines above the current line. 

To see records below the current line, instruct the Editor to move 
down in your file: 

down number 

where number is the number of lines below the current line. 



19 Delete a Line from Your File: Use the DELETE Subcommand 

To delete a line from your file, move up or down in the file so that the 
line you want to delete is the current line. When the line you want 
deleted is displayed as the current line, instruct the Editor to delete 
it: 

delete number 

where number specifies the number of lines deleted beginning with the 

current line. If you enter DELETE 9, the Editor deletes the current 

| line and the next eight lines following it. The new current line is the 

| one following the last deleted line. 



19 P.i§£lM Records in Your File: Use the TYPE Subcommand 

To display records in your file, enter the TYPE subcommand: 
type number 

where number is the number of lines you want displayed, beginning with 
| the current line. The last line displayed then becomes the current 
| line. If you are using a 3270 display terminal in display mode use the 

SCROLL, FORWARD, and BACKWARD subcommands to display records. 



29 Change the Contents of a Record: Use the CHANGE Subcommand 

To change the contents of a record, issue the CHANGE subcommand: 

change /string1/string2/ 

where stringl is the string of characters you want to replace and 
string2 is the string of characters you want to replace them with. 
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IP. Store the File and Bet urn to the CBS Environment: Use the FILE 
Subcommand 

To store the commands and the data you have created in your file, 
instruct the Editor to file your data for you, using the FILE 
subcommand. Before you issue FILE, however, you must return your virtual 
machine to the EDIT mode. So press the Beturn key to enter EDIT mode, 
and then issue FILE: 

file 

All of the records you created are now filed on your virtual disk. 
The FILE subcommand takes your virtual machine back to the CHS 
environment. CHS responds to the FILE subcommand vith a Beady Message, 
to let you know your virtual machine is back in the CHS environment. 

The subcommands just discussed should be adeguate for writing and 
editing a simple program. As you follow the program example you will 
see how these EDIT subcommands are used. 



A SAHPLE PB06BAH 

The program you are about to create is a sample program designed to 
familiarize you with the interactive facilities of VH/370. The program, 
when it executes, calls for you to enter a line of data in response to a 
direction from the program. It asks you to enter another item of 
information. Then, it tells you what you told it. 

Enter the program just as you see it. What you enter is shown in 
lowercase; the Editor responses are shown in uppercase. The first field 
the Editor allows you to enter is the label field, which begins with 
column 1. When you press the tab key, the type ball moves to the next 
tab setting on the terminal, and this lets the Editor know that the next 
field you enter goes in the operation field, which begins in column 10. 
When you press the tab key again, the Editor spaces to the operand 
field, beginning in column 16. 

There are several ways you can get a continuation mark in column 72; 
see the VH/370: EDIT Guide for this information. In this example, the 
$HABK edit macro is used. Tou must add the $HABK edit macro to your CHS 
system; it is not distributed with CHS. The VH/370: E DIT Guide tells 
you how to add it to your CHS system. 

Bote that the example shows one space after the third LINEDIT macro 
instead of pressing the tab key. The third LINEDIT macro line is so 
long that is does not fit if you tab to column 31. When you enter the 
third LINEDIT macro you must press the Beturn key twice after the last 
comma: once to enter the line and one to return to EDIT mode. Tou know 
you are in EDIT mode when EDIT: is displayed. Then you must enter the 
macro *$HABK'. This places an * continuation mark in column 72. To 
return to INPUT mode, enter •input 1 . 
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edit myfile assemble 

NEW FILE: 

EDIT: 

tabs 1 10 16 31 36 41 46 69 72 80 

input 

INPUT: 

When INPUT: is displayed, you continue entering your program. 

sample csect 



using sample, r1 2 

lr r12,r15 

st r14, savret 

linedit 

rd term 

linedit 

rdterm 



set up addressability 

load base register 

save return address 

text=' please enter your name' 

name 

text=« please enter your age' 

age 



linedit text=»hi, , you just told me you are 



EDIT: 
$mark 
input 
INPUT: 



name 

age 

savret 



sub=(chara,name,chara,age) ,rent=no 



1 r14, savret 

br r14 

eject 

dc cl130« ' 

dc C1130 1 

dc f«0» 

regegu 

end 



get return address 
return to caller 

name field 

age field 

save return address 



When you finish entering the program, you can display it, and then 
you should file it. If you display the program, it should be: 



SAMPLE 


CSECT 




USING SAMPLE, R12 




LR R12,R15 




ST R14, SAVRET 




LINEDIT 




RDTERM 




LINEDIT 




RDTERM 




LINEDIT TEXT=«HI, 




SUB= (CHARA, 




L R14, SAVRET 




BR R14 




EJECT 


NAME 


DC CL130« • 


AGE 


DC CL130* • 


SAVRET 


DC F»0» 




REGEQU 




END 



SET UP ADDRESSABILITY 

LOAD BASE REGISTER 

SAVE RETURN ADDRESS 

TEXT=»PLEASE ENTER YOUR NAME* 

NAME 

TEXT=«PLEASE ENTER YOUR AGE.' 

AGE 

, YOU JUST TOLD ME YOU ARE 

NAME, CHARA, AGE) ,RENT=N0 
GET RETURN ADDRESS 
RETURN TO CALLER 

NAME FIELD 

AGE FIELD 

SAVE RETURN ADDRESS 



Col 
72 

I 

y 



Creating and Executing Your Program 

This section describes the CMS commands you use to create, load, and run 
your sample program: EDIT, GLOBAL, ASSEMBLE, LOAD, and START. These 
commands represent the most basic method of creating and executing a 
program using CHS. 
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INPUT FOR THE PROGRAM 

To create the program file, enter the EDIT command to invoke the CMS 
Editor, 

edit sample assemble 

The Editor responds to the command by telling you that this is a new 
file and that you can begin creating it 

NEW FILE: 

EDIT: 

You then place your virtual machine in the INPUT mode by entering the 
INPUT subcommand 

input 

When you press the Return key, the Editor responds with the message 

INPUT: 

Now you can enter the program statements. When you have entered all 
of your program statements, press the Return key to return to the EDIT 
environment. Now issue the FILE subcommand to save the statements you 
have entered and to return to the CMS command environment. 



ASSEMBLING YOUR PROGRAM 

To assemble SAMPLE, you issue two commands: GLOBAL and ASSEMBLE. The 
GLOBAL command accesses libraries needed by the assembler during its 
execution. The ASSEMBLE command causes your program to be assembled by 
the assembler. You should enter both GLOBAL and ASSEMBLE just as they 
are shown here: 

global maclib cmslib 



inkla oamrtl 



CMS notifies you when the assembly is done by displaying a message at 
your terminal. You receive one of two kinds of messages: one to tell 
you there were no errors, the other to tell you there were errors and 
where they were in the program. In either case, a Ready message is 
generated to tell you that ASSEMBLE has completed execution. 

If there are no errors, the message is 

ASSEMBLER DONE 

NO ERRORS FLAGGED IN THIS ASSEMBLY 

R; 

If you have errors, you receive a message like 

ASSEMBLE DONE 

SAM00331 B EBRT 

IFO024 NEAR OPERAND C0LUMN1— UNDEFINED SYMBOL 

1 STATEMENT HAS FLAGGED IN THIS ASSEMBLY 

8 MAS HIGHEST SEVERITY CODE 

R(008) ; 
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If you receive the error message, you have to go back and correct 
your program; the assembler language error message you receive tells you 
where and hov you made the mistake. Use the EDIT command to correct the 
file: 

edit sample assemble 

This statement allows you to correct your source file. The Editor 
places your virtual machine in the EDIT mode and places the file in 
storage so you can edit it. You can now begin making corrections using 
the EDIT subcommands described in the first part of this section. 

When you have corrected the program, file it again and reassemble it 
(assemble sample). This time you need not enter the GLOBAL command, 
since the first GLOBAL command is in effect for the duration of your 
terminal session. 

If the program assembles with no errors, you can load it in virtual 
storage and execute it. 



LOADING AND EXECUTING THE PROGRAM 

The CMS LOAD and START commands load your program in virtual storage and 
begin its execution. The LOAD command processes the relocatable object 
code produced by the ASSBHBLE command. The LOAD command loads the 
assembler TEXT file into storage and establishes the proper linkage. 
Enter the LOAD command as it is shown here: 

load sample 

After you press the Return key, CHS responds with a Ready message 
(R;) when your program is loaded successfully. 

Now enter the START command to begin execution of the program: 

start sample 

The virtual machine, with your program now in control, prompts you with 
the messages supplied by your program: 

PLEASE ENTER YOUR NAME: 
PLEASE ENTER YOUR AGE: 

After you answer its questions, your program writes you a message and 
returns a Ready message. 



LOGGING OFF 

When you want to end the terminal session, use the LOGOFF command, 
logoff 
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Virtual System Console 

The major differences between operating on the real machine and 
operating under CP are: 

• You can enter CP commands by entering CP mode, or by issuing the #CP 
command while a virtual machine's console is able tc read. 

• The Reguest key of a real operator's console is simulated by 
signalling attention once from the terminal. 

To reply to messages from a virtual machine operating system, you: 

| • Must enter VM mode (if you on a 2741 communication terminal) . 

• Enter the information requested. 

• press the carriage return (Return) key on the 2741 Communication 
Terminal (or eguivalent on other terminals) . 

If communication with CP is reguired before responding to specific 
error messages issued by some virtual machine operating systems, enter 
CP mode and perform the necessary console functions. When control 
returns to the virtual machine environment, the virtual machine read is 
canceled by a unit exception and the virtual machine operating system 
responds by reissuing the read. The reguired virtual machine response 
may then be entered. 

The Cancel key of the system console keyboard is simulated by the 
Attention key on the 2741. To enable the CPU operator to make input 
line and character corrections to operating system responses, the VM/370 
logical editing symbols may be used. 



Attaching Devices 



When a virtual machine operating system requires a specified device, as 
in a MOUNT reguest, you should do one of the following: 

• If the device is already defined as part of the virtual machine 
configuration, enter CP mode. Then enter the CP command READY cuu 

(with cuu replaced by the virtual I/O device address) , followed by 
the CP BEGIN command. This is the virtual machine eguivalent of 
physically making a device ready, if it is not already in a ready 
state. 

• If the device is not a standard device already defined as part of the 
virtual machine configuration, enter CP mode, and issue the CP DEFINE 
command to add the device to the virtual machine configuration. If a 
DASD device is already defined for some other user in the VM/370 
directory, you can use the CP LINK command to add the device to your 
virtual machine configuration. Otherwise, send a message to the 
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system operator to attach it to your virtual machine. When the real 
device is ready, enter the BEGIN command. 

Note: If the virtual device is an attached real device at the time you 
need it mounted, the real device can be taken out of and put back into 
ready status to cause an interrupt. 



TAPE DEVICES 

Tape drives, because they cannot be shared, are usually not defined in 
the VM/370 directory as part of a virtual machine configuration. When 
you require a tape drive for a job, a system operator with privilege 
class B must attach an available real device to ycur virtual machine 
with the virtual device address you require. When the job involving 
that tape drive is complete, you can issue a DETACH command, naming the 
virtual device address of the tape to release the tape. In this way, 
real tape drives are allocated to a virtual device only for the duration 
of the jobs that need them. 



Loading an Operating System into a Virtual Machine 

Figure 10 shows how you could load an OS/MFT system on a virtual 
machine, and the subsequent mounting of a virtual device at address 
232. (For clarity, the information you enter is shown in lower case, 
and messages displayed by CP and OS are shown in uppercase) . 

The virtual machine that is to run OS must have a configuration 
compatible with that for which the operating system's nucleus was 
generated. An example of an appropriate VM/370 directory entry is: 

USER BATCH PASSWORD 512K 
ACCOUNT NUMBER BIN10 
OPTION REALTIMER ISAM 
CONSOLE 01F 3215 
SPOOL C 2540 READER A 
SPOOL D 2540 PUNCH A 
SPOOL E 1403 A 
DEDICATE 230 BATCH1 
DEDICATE 231 BATCH2 
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logon os/ift 

ENTER PASSWORD: 

(Printing of the password is inhibited) 

LOGON AT 13:2U:30 EST THURSDAY aa/dd/yy 
ipi 230 



IEE007A READY 

set date = 72. 355, Q = (231) 

start rdr, 00c 

start vtr, OOe 

start 

IEF233A B 232, VOLABC, JOB, STEP 



! 

#cp link to usera 330 as 232 v pass 
DASD 232 LINKED TO R/H 



#cp ready 232 



IPL the OS systea residence device. 

You Bust respond to all OS IPL coaaands. 



OS ready aessaqe. 



OS requests operator to aount a pack labeled 
"VOLABC" on 232. 

You press the attention key once to present 
an interrupt to OS. 

Because the LINK coaaand was prefaced by #CP, 
the OS virtual aachine acts as though you 
had pressed the CANCEL key, and issues 
another READ to the systei console. The LINK 
coaaand is passed directly to CP. 
You request that a disk belonging to usera, 
with a virtual address of 330, be linked 
to your own virtual aachine. You issue the 
CP LINK coaaand to access that other user^s 
disk, with virtual address 232 in his virtual 
aachine. Alternately, you could issue the 
"vary 232, online" OS coaaand. 

Then enter READY to siaulate a ready 
interrupt to OS and end the read by pressing 
the carriage return or Enter key. 



Figure 10. Loading an OS/HFT Virtual Machine 



Spooling Virtual Console I/O 



CP lets you spool your virtual machine's console input/output to disk, 
instead of, or in addition to, having it displayed at your terminal. 
The data spooled includes messages from or to the virtual machine 
operating system, and from or to CP. This facility, invoked by the 
SPOOL CONSOLE command, is particularly useful when the virtual machine 
is executing vith the terminal disconnected, or when the virtual machine 
console is a display device, since the virtual console output, which 
would otherwise be lost, is saved on disk. The saved data is later 
printed on the real printer. 

If the real printer cannot print lower-case characters, the operator 
can use the FOLD option when he loads the buffer for the print train 
image. This causes the printer to print, in upper case, data that you 
enter in lower case. 

You can invoke or terminate virtual console I/O spooling at any time 
and as often as you like. If the console file is not closed when you 
log off (or are forced off) the VH/370 system, CP closes the console 
spool file and schedules it for printing. 
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Reading Cards in a Virtual Machine 

When an operating system such as DOS, DOS/VS, or OS/PCP, MFT, MVT, VS1, 
or VS2 is running batch production jobs in a virtual machine, it may 
occasionally be necessary to dedicate a real card reader to that virtual 
machine. In that case, jobs are entered through the card reader in 
exactly the same way they are entered on a standalone system, and no 
double spooling occurs. 

If, however, there is no extra reader available to dedicate in such a 
manner, or if the virtual machine is being run from a terminal not 
located near a real card reader, other methods of handling card input 
are necessary. 

Card images can be placed into the (spooled) virtual card reader of 
your virtual machine in four ways: 

• A card deck can be placed in the real card reader and read by VM/370. 
The deck must be preceded by a special VM/370 identification (ID) 
card specifying your virtual machine userid. VM/370 reads the cards 
and transfers the card images to your virtual machine's virtual card 
reader as a spool file. When your virtual machine issues a read to 
the card reader, VM/370 presents the cards, one at a time, to the 
virtual machine. The format of the ID card is described in the CMS 
READCABD command description. 

• A virtual machine's printer can transfer printer listing images and 
the punch can transfer punch images to its own (or to some other 
user's) virtual card reader. CP can handle up to 150-character 
records in virtual card readers. The CP SPOOL transfers these unit 
record files. For example: 

spool punch to usera 

causes all cards punched to be transferred (after the punch file is 
closed) as an input file to usera's spooled card reader. 

CMS cannot print files that have records greater than 160 characters 
long. However, CMS can display records greater than 160 characters 
long. 

• Via the CP TRANSFER command, you can transfer your virtual reader 
f ile (s) to another user's virtual reader, or retrieve previously 
transferred files back to your own virtual reader. 

• A card deck can be placed in the card reader of any of the remote 
stations supported by the Remote Spooling Communications Subsystem 
(RSCS) . The same VM/370 ID control card, as mentioned previously, 
must precede the deck. RSCS receives the card file and spools it to 
the specified VM/370 user's virtual card reader. 

Normally you should find it helpful to set the following spooling 
options for your virtual card reader: 

spool 00c cont noeof 

where: 

cont specifies that reading be "continuous" (that is, not to indicate 
an EOF condition to the virtual machine after each input file, 
but to continue reading all the card images until the reader 
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files spooled to the virtual machine are exhausted) . If this 
option is not in effect, a unit exception is reflected to your 
virtual machine at the end of each spooling file. This option 
eliminates the need to repeatedly enter the CP READY and CLOSE 
commands between the reading of each spooled file. 

noeof indicates that the virtual reader's end-of-file button is 
assumed not to have been pushed. When all reader spool files 
are exhausted, an intervention-required status pending is 
reflected to the virtual machine. When additional reader files 
are transfered to the virtual card reader, a device end 
interrupt is reflected to the virtual machine, and card reading 
normally resumes automatically (because a device end interrupt 
"wakes up" the virtual machine) . 

The operator of a virtual machine operating system such as OS or DOS 
may choose to prepare his own job streams at his terminal using the CMS 
Editor facilities, and then IPL another operating system to process the 
job streams. This procedure is discussed under "Using Multiple 
Consecutive Operating Systems. " 



I Printing and Punching in a Virtual Machine 

VM/370 provides unit record spooling facilities. When operating systems 
that also provide unit record spooling facilities are running in a 
virtual machine, double spooling of printed and punched output may 
occur. If you wish, you can eliminate one of the spooling facilities. 

To eliminate CP spooling, a real printer or punch can be temporarily 
attached to a virtual machine, or dedicated to a virtual machine in the 
VM/370 directory via the DEDICATE statement. In either case, CP 
performs no spooling for that virtual device. Interrupt processing can 
be initiated by the virtual machine whenever it receives control of the 
CPU from CP. 

CP spooling has priority over any virtual machine execution. The 
real printer and punch are better utilized by CP than by a virtual 
machine. CP spooling provides more efficient shared use of a limited 
number of readers, printers, or punches by many virtual machines. 



OS spooling can be eliminated by using OS JCL in the form DNIT=00E or 
UHIT=00D instead of SYSODT=A or SYSOOT=B, where 00E and 00D are virtual 
device addresses. 

DOS POWER spooling can be eliminated by using the Job Entry Control 
Language (JECL) option of POWER and by indicating no spooling on the 
JECL control statements for dedicated spooling devices. 

When printer or punch spooling is performed by CP, the CP CLOSE 
command specifying the virtual printer or punch address should be issued 
periodically. This releases previously finished and stacked output 
files for CP spooling and results in better utilization of the DASD 
spooling areas and of the unit record devices. 

CMS has no spooling facilities of its own, and does not cause double 
spooling when running in a virtual machine. It does not support an 
attached or dedicated printer, punch, or reader, and must use the 
facilities of CP. CMS closes the virtual printer or punch after the 
completion of each command that uses them. 
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I Disconnecting the Terminal 

Once you load a virtual Machine operating system and start jobs you say 
want to use your terminal for some other purpose while the batch jobs 
are running. The DISCOHN command allows you to disconnect your terminal 
from the VM/370 system, but allows the virtual machine to continue 
operation. You can reconnect your terminal by issuing the LOGOS 
command. 

Unless the CP command, SPOOL COMSOLE START, is issued to spool the 
virtual console and CP output, all "writes" or output messages to the 
virtual console are ignored. 

A HOLD option is provided with the DISCONN command to prevent a 
communication line in a switched line configuration from being 
disabled. 

Disconnecting the terminal frees it for other uses, but is useful 
only for operating systems that can run in an unattended mode. If a 
virtual machine that is running disconnected issues a "read" to the 
virtual console or enters a disabled wait state, virtual machine 
execution is halted and a 15-minute time-out begins. If you do not 
re-establish your connection to the VM/370 system (by logging on again) 
within 15 minutes, you are logged off the system. 

A virtual machine may also be placed in disconnect status 
automatically. If a teleprocessing line error occurs, or you turn off 
your terminal without logging off, the virtual machine is disconnected 
and execution stops. (If you turn off a 3270 without logging off, the 
virtual machine is disconnected if someone sends a message to the 
terminal.) A 15-minute time-out begins. If you do not log on again 
within 15 minutes, your virtual machine is logged off the system. 

When a disconnected machine is logged off, VM/370 closes all open 
spool files and schedules them for printing or punching. 

You reconnect to a disconnected virtual machine via the normal logon 
procedure. (If there was a read active on the terminal at the time of 
disconnect, you may have to issue a BESET command for the terminal.) 
Your running virtual machine is placed in the CP command mode. To 
resume execution of the virtual machine operating system, issue the 
BEGIN command. 

For example, (a) shows the disconnect procedure, and (b) shows the 
subsequent reconnect, as long as PROGA is still running when DSERA 
reconnects. 

(a) 
logon usera 
ENTER PASSWORD: 

(displaying of the password is inhibited) 
LOGON AT 05:30:30 EST FRIDAY mm/dd/yy 
ipl 190 

CHS VERSION 2 LEVEL 
run proga 
• •• 
CP 

disconn 
DISCONNECT AT 05:35:30 EST FRIDAY mm/dd/yy 
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(b) 
logon usera 
ENTER PASSWORD: 

(displaying of the password is inhibited) 
RECONNECT AT 07:42:45 EST FRIDAY mm/dd/yy 
begin 

Note: A PROFILE EXEC procedure (if one exists) is not executed 
automatically when you log on after disconnecting. Also, if you set a 
system option (such as specifying TERMINAL APL ON) before you 
disconnect, that option may be returned to its default when you log on 
again. 



I Using Multiple Consecutive Operating Systems 

You may reguire the facilities of more than one operating system during 
a single terminal session. 

When you run an operating system such as OS, DOS, OS/VS1, OS/VS2, or 
DOS/VS from a terminal, you can use the CMS Editor facilities to create 
and modify job streams. 

If you are an applications programmer who normally uses CMS to 
interactively create, modify, and test your programs you may reguire 
facilities not supported or available in CMS for compilation (for 
example, programs using DOS macros) or for execution (for example, any 
DOS object program, or any OS object program that utilizes certain OS 
supervisory functions and access methods not simulated under CMS) . 

The following technigue uses multiple operating systems 
consecutively. Job control cards, compiler or assembler source 
programs, and test data streams are created and modified at the terminal 
under control of the CMS Editor. Then the job stream is executed, only 
after control has been passed to an appropriate operating system with 
the necessary facilities. 

In this way, you can use the terminal-oriented facilities of CMS to 
create and update source pronrais and JCL. When you are ready to 
compile or test, you can give control of your virtual machine to DOS or 
OS. After execution is finished, you can transfer the printer and punch 
output back to CMS for selective scanning and displaying at the 
terminal. 

This approach assumes you have created source program files and data 
files under CMS. To execute under another operating system (in this 
example, OS) you must also create JCL records that specify the 
compilation, link edit, or execution, as appropriate. These records are 
created under CMS and named with a distinctive filename and filetype 
(for example, PLICOMP JCL). Job control records, source program files, 
and data files can then be merged together in the virtual card reader to 
form a single OS job stream. CP and CMS commands (shown in Figure 11) 
create and transfer this job stream. 

TRANSFERRING OUTPUT 

The CP SPOOL command transfers card images from the virtual card punch 
of one virtual machine to the virtual card reader of that same or some 
other virtual machine. During this time, no real cards are punched or 
read; CP manages the transfer of CMS card-image data files through disk 
spooling operations only. 
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Figure 11 shows how files are transferred between virtual machines. 
The virtual machine is in CMS mode at the start of the example. The 
command "SPOOL 00c cont eof" specifies that reading be continuous until 
all files spooled to the virtual machine are exhausted and the virtual 
end-of-file button on the reader is pushed. NOHEADEB specifies that no 
special control cards are to be inserted in front of each punched file. 
Virtual device 230 is an OS system volume, virtual device 231 contains 
the OS job queue, SYS1 .SYSJOBQE. All standard OS responses (for 
example, R;T=0.04/0. 12 09:36:08) are omitted from the example; however, 
the OS READY message is included to more fully illustrate the IPL 
sequence. Also, assuming you are using a 2741, you must press the 
Attention key before entering each OS command. The attention interrupts 
are not shown in Figure 11. 



CMS 

cp close 00c 

cp close OOd 

cp spool OOd to * 

punch jobcard jc1 (noheader) 

punch plicomp jc1 (noheader) 

punch plimain pl1 (noheader) 

punch asmcomp jc1 (noheader) 

punch asmsub assemble (noheader) 

punch linkgo jc1 (noheader) 

punch godata dat (noheader) 

punch slshstar jc1 (noheader) 

cp spool 00c cont eof 

cp ipl 230 

Note: The following are issued once under OS control: 

IEE007A READY 

set date=xx.355,Q= (231) 

start rdr,00c 

start wtr,00e 

start 

Figure 11. OS Job Stream Transfer 



To transfer files between virtual machines, you must have access to 
both operating systems being used. Access to both systems can be 
provided either in your virtual machine's VM/370 directory entry, or 
dynamically before loading the new system. 

Figure 12 illustrates a virtual machine configuration and the 
corresponding VM/370 directory control statements. Virtual device 
addresses 190 and 191 contain the CMS system and user disk area. 
Virtual device addresses 230 and 231 contain the OS system and user disk 
area. The two systems use a common card reader, card punch, printer, 
and console. 
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I 



DSEB 0S2 PASSWORD 
ACCOUHT NUHBEB BIM16 
CONSOLE 01F 3215 
SPOOL C 2540 BEADEB 
SPOOL D 2540 PUNCH 
SPOOL E 1403 
LINK JFK 230 230 B 
LINK CHSSYS 190 190 BB 
HDISK 231 2314 120 82 H 
HDISK 191 2314 101 10 UDISK1 WB BPASS WPASS 



I 



I 



j Figure 12. Directory Entry for Alternating Operating Systens 



CONFIGUBATIONS 



| You can alternate operating systens nore simply if: 

| • The devices used by both systens are supported at the sane device 
| address, and 

| • The connon addresses are not used to support different devices 

| If these two conditions do not exist, you nust nodify the virtual 
I nachine configuration before each IPL of a new systen. 

| If the two systens reguire online typewriter keyboards at different 
I addresses, the CP DEFINE connand can be used to change the address of 
j the virtual systen console. For example, if the OS systen specified in 
| Figure 12 reguired an online typewriter keyboard at address 01F, issue 
| the connand 

| cp define 009 as 01F 

| before loading 230. Mhen the OS job strean is conpleted, issue the 
I connand 



cp define 01F as 009 



| before loading CHS. Virtual storage size can be changed and virtual 

| card readers, printers and punches can be added with this procedure. 

| If the systens expect different device types at the sane address (for 

| exanple, in Figure 12 CMS expects a 2314 at address 191, but the OS 

j systen night be generated to support a 3330 at that address) , the connon 

| address nust be assigned to the appropriate device each tine a new 

I systen is loaded. If CHS is running with a disk at address 191, you 

| should issue the following connand before loading OS: 



cp detach 191 



| An appropriate device can then be added to the virtual nachine at 

| address 191 either before loading, or in response to a nount reguest 

j fron the OS systen. 

I Note: For direct access storage devices, the above procedure is 

| necessary even if both systens support the sane device type at the same 

| address. The disk fornat used by CHS is unigue, and is not conpatible 

I with that of other operating systens. Files can be shared between CHS 

| and OS or DOS only through the spooling facilities of CP. 
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I Execution Control 

A string of arguaents can be passed to your program from the terminal 
when execution is begun with the CMS START command. If arguments are 
specified, the storage address of a parameter list is placed in general 
register 1. The parameter list is a string of double words, one 
argument per double word. The first argument is the entry operand. 
Other arguments are accessed with displacements of 8, 16, 24, and so on, 
from the address contained in register 1 when execution begins. For 
example: 

load proga 

start epg 071374 

causes execution to begin at a control section or entry point named 
EPG. When execution begins, general register 1 points to a string of 
two double words, the first containing EPG, the second containing 
071374. 

If a program is to be executed freguently, you can create a 

non-relocatable copy of it on one of your disks. Subsequent invocation 

of this program causes the absolute module to be read from disk storage, 
ready to begin execution. 
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Part 2: Reference Information 



This part of the publication contains reference information. Section 7 
contains all the formats and rules for using CHS commands. Section 8 
contains the formats and rules for using CP commands. 



Notational Conventions 

The notation used to define the command syntax in this publication is: 

• Truncations and Abbreviations of Commands 

Where truncation of a command name is permitted, the shortest 
acceptable version of the command is represented by uppercase 
letters. (Remember, however, that VH/370 commands can be entered 
with any combination of upper and lowercase letters.) The example 
below shows the format specification for the FILEDEF command. 

Flledef 

This representation means that FI , FIL, FILE, FILED, FILEDE, and 
FILEDEF are all valid specifications for this command name. 

Operands and options are specified in the same manner. Where 
truncation is permitted, the shortest acceptable version of the 
operand or option is represented by uppercase letters in the command 
format box. If no minimum truncation is noted, the entire word 
(represented by all capital letters) must be entered. 

Abbreviations are shorter forms of command names, operands, and 
options. Abbreviations for command names are shown below the full 
name in the format box. Abbreviations for operands and options are 
shown in the description of the individual operands and options that 
follows the format box. For example, the operand READER has both a 
minimum truncation and an abbreviation. In the format box it is 
shown as: 

Reader 

indicating that the minimum truncation is R. In the discussion of 
the READER operand that follows, it is shown as: 

READER 
RDR 

indicating that the abbreviation is RDR. Thus, the acceptable 
specifications for the READER operand are: R, RE, REA, READ, READS, 
READER, and RDR. 

In some cases what appears to be a minimum truncation is really the 
only valid abbreviation. For example, the abbreviation for MEMBER is 
MEM. Only these two forms are valid and no truncations are allowed. 
The format box contains 
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MEMBER 



{ n r} 

and the description that follows the format box is 



MEMBER 
HEM 



!»...} 



• The following symbols are used to define the command format and 
should never be typed when the actual command is entered. 

underscore _ 

braces { } 

brackets [ ] 
ellipsis 

• Uppercase letters and words, and the following symbols, should be 
entered as specified in the format box. 

asterisk * 

comma , 

hyphen 

egual sign = 

parentheses ( ) 

period 

colon : 

• Lowercase letters, words, and symbols that appear in the command 
format box represent variables for which specific information should 
be substituted. For example, "fn ft fm" indicates that file 
identifiers such as "HYFILE EXEC A1 n should be entered. 

• Choices are represented in the command format boxes by stacking. 

A 

B 
C 

• An underscore indicates an assumed default option. If an underscored 
choice is selected, it need not be specified when the command is 
entered. 

Example 

The representation 

A 
B 

C 

indicates that either A, B, or C may be selected. However, if B is 
selected, it need not be specified. Or, if none is entered, B is 
assumed. 
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• The use of braces denotes choices, one of which must be selected. 

Example 

The representation 



{'■\ 

indicates that you must specify either A, or B, or C. If a list of 
choices is enclosed by neither brackets or braces, it is to be 
treated as if enclosed by braces. 



• The use of brackets denotes choices, one of which may, be selected. 



Exaj 
The 


representation 




r t 

( A ( 
1 B | 
1 C | 

L J 



indicates that you may enter A, B, or C, or you may omit the field. 

An ellipsis indicates that the preceding item or group of items may 
be repeated more than once in succession. 

Example 

The representation 

(options. . .) 

indicates that more than one option may be coded within the 
parentheses. 
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Section 7: Format and Usage Rules for CMS Commands 



CMS Command Summary 

This section contains descriptions of the commands acceptable in the CMS 
environment. Figure 13 contains an alphabetical list of the CMS 
commands and the functions performed by each. Unless otherwise noted, 
CMS commands are described in this manual. 



Command 



Usage 



ACCESS 

ASM3705* 

ASSEMBLE 

CMSBATCH 

COBOL 2 

COMPARE 

CONVERT* 

COPYFILE 

CP 

CPEREP' 

DDR*,3 

DEBUG* 

DIRECTS 3 

DISK 



Define direct access space for a CMS virtual machine, 
create extensions and relate the disk space to a logical 
directory. 

Assemble 3704/3705 source code. 

Assemble Assembler Language source code. 

Invoke the CMS Batch Facility. 

Compile ANS Version 4 COBOL source code. 

Compare all or part of records in two existing disk files. 

Convert free form FORTRAN statements to fixed form. 

Copy files according to specifications. 

Enter CP commands from CHS environment. 

Dump error information which was recorded by VM/370 error 
recording routines. 

Perform backup, restore, and copy operations for virtual 
disks. 

Enter DEBUG subenvironment, DEBUG mode. 

Set up VM/370 directory entries. 

Perform disk-to— card and card— to-disk operations for CMS 
files. 



1 This command is described in the VM/370; Planning and System 

Generation Guide. 
2 This command invokes an IBM Program Product, available from IBM for 

a license fee. 
3 This command is described in the VM/370: Operator's Guide. 
♦This command is described briefly in this manual and in detail in the 

VM/370 : System Programmer's Guide. 
i Z ZZ "", . T 

Figure 13. CHS Command Summary (Part 1 of 4) 
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Command | Usage 

BDIT S | Enter EDIT subenvironment, EDIT mode. 

ERASE | Delete files from user disks. 

EXEC 6 | Process special procedures made up of frequently used 
I sequences of commands. 

FILEDEF | Provide simulation of OS job control language data 
(definition (DD) statements. 

FORMAT | Prepare disks in CBS 800-byte block format. 

FORTGI 2 | Compile FORTRAH source code using the G1 compiler. 

FORTHX 2 | Compile FORTRAN source code using the H-extended compiler 

GEN3705* | Generate an EXEC file that assembles and link edits the 
| 3704/3705 control program. 

GEHDIRT | Create auxiliary module directories. 

GENHOD | Generate absolute non-relocatable files (MODULE files) . 

GLOBAL | Define specific CHS libraries to be searched for macros 
land subroutines. 

GOFORT 2 | Compile FORTRAN source code and execute the program just 
| compiled using Code and Go compiler. 

INCLUDE | Bring additional TEXT files into storage and establish 
| linkage. 

LISTDS | List information about data sets on an OS disk. 

LISTFILE | List information about user CHS files. 

LKED* | Link edit the 3704/3705 control program. 

LOAD (Bring TEXT files into storage and establish linkages. 

LOADHOD | Bring a single HODULE file into storage. 

HACLIB | Create and modify CHS macro libraries. 



1 This command is described in the VH/370: Planning and System 

Generation Guide. 
2 This command invokes an IBH Program Product, available from IBH for a 

license fee. 
5 This command is described briefly in this manual and in detail in the 

yjZJlQ: EDIT Guide. 
*This command is described briefly in this manual and in detail in the 

VH/370; EXEC fiserj.s Guide. 
i Z "* "" _ 

Figure 13. CHS Command Summary (Part 2 of 4) 
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Command 

HODHAP 

HOVEFILE 

HCPDUHP*,' 

PLIC« 

PLICB* 

PLIOPT* 

PRIHT 

PUNCH 

QOEBI 

READCARD 

RELEASE 

REMAKE 

RUM 

SAVENCP* 

SCRIPT* 



I Usage 

Display load map of a MODULE file. 

Hove data fro« one device to another device of the same or 
different type. 

Process CP spool reader files created by 3704/3705 
dumping operations. 

Compile the PL/I source code using the PL/I Checkout 
Compiler. 

Execute the PL/I object code generated by the PL/I Checkout 
Compiler. 

Compile the PL/I source code using the PL/I Optimizing 
Compiler. 

Spool a specified CBS file to the virtual printer. 

Spool a specified CHS file to the virtual punch. 

Reguest information about a CHS virtual machine. 

Read data from spooled card input device. 

Hake a disk and its directory inaccessible to a CHS virtual 
machine. 

Change the name of a CHS file or files. 

Initiate series of functions to be performed on a file. 

Read 3704/3705 control program load into virtual storage 
and save an image on a CP— owned disk. 

Format and print documents according to embedded SCRIPT 
control words in the document file. 



*This command is described in the VH/ 370; Planning and System 

2 This command invokes an IBH Program Product, available from IBH for a 

license fee. 
3 This command is described in the VH/370: Oj>erator^s Guide. 
7 This command invokes a text processor that is an IBH Installed User 
Program, available from IBH for a license fee. 
i 

Figure 13. CHS Command Summary (Part 3 of 4) 
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Comaand | Usage 

SET (Establish, set, or reset CHS virtual ■acbine 
characteristics. 

SORT I Arrange a specified file in ascending order according to 
specified fields in the data record. 

START | Begin execution of programs previously loaded. 

STATE IVerify the existence of a file. 

SVCTRACE I Record information about supervisor calls. 

SYNONYM llnvoke a table containing synonyms you have created for 
CHS commands. 

TAPE I Perform tape-to-disk and disk-to-tape operations for CHS 
files. 

TAPFDS I Load OS partitioned data set (PDS) files or card image 
files from tape to disk. 

TESTCOB 2 | Execute the OS COBOL Interactive Debug Program Product. 

TESTFORT 2 I Execute the FORTRAN Interactive Debug Program Product. 

TXTLIB | Generate and modify text libraries. 

TYPE | Display all or part of a file at the terminal. 

UPDATE I Hake changes in a file as defined by control cards in a 
control file. 

VHFDUHP 3 IFormat and print system ABEND dumps. 

VSBASIC 2 I Compile and execute VS BASIC programs under CHS. 

VSBUTIL 2 | Convert BASIC 1.2 data files to the format reguired by 
VS BASIC. 

ZAP 1 , 3 IHodify or dump LOADLIB, TXTLIB, or HODULE files. 



*This command is described in the VH/370; Planning and System 

Generation Guide. 
2 This command invokes an IBH Program Product, available from IBH for a 

license fee. 
3 This command is described in the V H/3 70; Operator's Guide. 



Figure 13. CHS Command Summary (Part 4 of 4) 
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Any of the commands listed in Figure 13 may be entered when you are 
running CMS in your virtual machine, the terminal is idle, and the 
virtual machine is receptive for input. If however, CBS is processing a 
previously entered command and your typewriter terminal keyboard is 
locked, you must signal your virtual machine via an attention 
interrupt. The system acknowledges the interrupt by unlocking the 
keyboards Now you can enter commands. If your terminal is a display 
device, there is no problem of entering commands while the virtual 
machine is busy as its keyboard remains unlocked for additional command 
input. Note that in these circumstances the most recent command is 
stacked and is not executed until the command that is currently 
executing completes. 

In addition to the commands listed in Figure 13, there are seven 
commands called Immediate Commands which are bandied in a different 
manner from the others. They may be entered while another command is 
executing by pressing the Attention key (or its eguivalent) and are 
executed immediately. The Immediate commands are: 

HB - Halt batch execution 

HO - Halt tracing 

HT - Halt typing 

HX - Halt execution 

HC - Resume tracing 

RT - Resume typing 

SO - Suspend tracing 
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ACCESS 



ACCESS 



Use the ACCESS cob Band to acquire disk 
directories in storage to be used during a 
File Directory is the disk-resident file di 
for each CBS file on a virtual disk. A 
directory created in storage when the ACCE 
contains an entry for each CBS file that is 
virtual machine. The specifications of the 
entries in the Dser File Directory. The f 
is: 



space and to set up file 
teriinal session. A Baster 
rectory containing an entry 
User File Directory is the 
SS conmand is executed. It 
available to you in your CBS 
ACCESS coasand determine the 
ormat of the ACCESS command 



r t 

ACcess | |cuu mode[/ext [ f n [ft [fm]]]]| [ (options. ..[)] ] 

L J 



op tions : 

r t 

IHOPHOFI 
| ERASE | 

L J 

[NODISK] 



where: 
cuu 



makes the disk at the specified virtual device address 
available. This field must be specified if other than the 
default value is desired. The default value is 191, except 
when the NODISK option is specified. (When NODISK is 
selected, the only disk accessed is the system disk and any of 
its extensions.) 



Note that 000 is not a valid address. 

mode assigns the one-character filemode letter to the disk being 
accessed. This field must be specified if cuu is specified 
(except when the NODISK option is selected) . The default 
value is A. 

ext indicates the mode of the parent disk. The User File 
Directory of this disk is logically associated with the User 
File Directory of the read-only extension. There must not be 
a blank preceding or following the slash (/) . 

fn searches the Baster File Directory of the disk being accessed 
and includes the files with the specified filename in the User 
File Directory for that disk. An asterisk coded in this field 
means that all filenames are to be included. (See Note 5.) 

ft searches the Baster File Directory of the disk being accessed 
and includes the files with the specified filetype in the User 
File Directory for that disk. If an asterisk is coded in this 
field, all filetypes are included. (See Note 5.) 

fm searches the Baster File Directory of the disk being accessed 
and includes the files with the specified filemode in the User 
File Directory for that disk. An asterisk coded in this field 
means that all files on the disk specified by the filemode 
letter and device address are selected, regardless of the 
filemode number. (See Note 5.) 
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ACCESS 

Mote: An asterisk (*) , preceded by any number of characters for filename 
or filetype, allows the specified characters to be used as the leading 
characters for that identifier. For example , ABC* for fn allows access 
to all files with filenames beginning with ABC. 

Options 

NOFBOF suppresses execution of a PROFILE EXEC file (see Note 1) . 
This option is valid only if the ACCESS command is the 
first command entered after an IPL of the CHS operating 
system. On subsequent ACCESS commands, the SOFROF option 
is ignored. 

| EBASE creates a User File Directory with no entries for the 

| disk being accessed; this option is valid only for disks 

in read/write mode. The Master File Directory on the 

disk remains unchanged; only. the directory in virtual 

storage is altered (see Note 3) . 

NODISK lets you gain access to the CMS operating system with no 
disks accessed except the system disk and its 
extensions. This option is valid only on the first 
command you enter after loading CHS. If NODISK is 
specified, no other operands or options may be used. 



Notes 

1. The PROFILE EXEC file is a user-generated EXEC procedure often used 
to perform initialization and to set system parameters reguired by 
the virtual machine. For example, whenever programs that use 
macros are assembled or compiled, the PROFILE EXEC procedure can 
issue the GLOBAL command to indicate where the system should search 
for the macros. For OS programs, the PROFILE EXEC procedure can 
issue FILEDEF statements for the files to be used. 

2. If an ACCESS command is not entered as the first command after an 
IPL command for CHS, the command: 

access 191 a 

is automatically performed and the PROFILE EXEC file, if one 
exists, is executed. Any disk being accessed must previously have 
been formatted using the CHS command FORHAT. 

3. If an ACCESS command with the ERASE option is entered by mistake, 
you can regain access to the existing files on the disk either by 
issuing another ACCESS command without the ERASE option, or by 
issuing a RELEASE command for the disk. Since the ERASE option 
does not alter the Haster File Directory or disk files, but only 
specifies that the directory built in virtual storage is to contain 
no entries, the original disk files can be recovered as long as 
they were not altered. However, if a CHS command is executed which 
causes a new file to be written on the disk, the Master File 
Directory is updated and the files which were on the disk before 
the execution of the ACCESS command with the ERASE option are no 
longer available. The space previously used for the erased files 
is now available for new files. 

4. If the initial ACCESS command (either explicit or implied) 
encounters an error, a message is displayed at the terminal and you 
can enter another command; no disk has been accessed at this time. 
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5. The filename, filetype and filemode can only be specified with 
disks which are accessed as read-only extensions. Files with a 
■ode number of are not be accessed in this case. 

6. If you have disk addresses 190, 191, 192, and 19E defined in the 
VM/370 directory, or if they are defined before you IPL CMS, these 
disks are accessed as the S, A, D, and I disks, respectively. The S 
and Y disks are read-only disks. 

| 7. If you are using ACCESS to access a read-only OS or DOS disk, you 
cannot specify the fn, ft, or fm operands, nor can you specify any 
options. 

| 8. A read-only OS or DOS disk cannot be accessed unless a CMS A-disk 
is already accessed, in read/write iode. 

| 9. Only one virtual machine at a time can access a disk in read/write 
I mode. 



r - — - — - — - . _ , . .. 

| Command | Result 


| ACCESS 192 B | Makes all files on 192 (which is to become the 
| | B— disk) available for reading. 


| AC 192 B/B ABC | Provides read— only access to all files on the 
I |B— disk with a filename of ABC. 


I ACC 192 B/B ABC* |Provides read-only access to all files on the 
I IB-disk whose filenames have ABC as the first 
I Ithree characters. 


| ACCE 192 B/B ABC * B2 |Provides read-only access to all files on the 
I | B— disk that have a filename of ABC and that 
I | are in read— only mode (mode number of 2) . 


! ACCES 191 A/A (Places the A— disk in read-only mode. 


| ACCESS 194 D/A | Makes the D— disk a read— only extension of the 
| I A— disk. The A— disk must have been accessed 
| | before this command is issued. The effect of 
I jthis can be negated by issuing 
| | ACCESS 194 D 


| ACC (NOPROF) | Accesses 191 as the A-disk and does not 

I | execute your PROFILE EXEC file if this is the 

| jfirst command executed after you load CHS. 


| AC 191 A (ERASE) |Hakes 191 available as the A disk but builds 
I I the file directory in virtual storage with no 
| | entries. All space on the disk becomes avail- 
| | able for new files, when the execution of a 
| JCMS command causes the Master File Directory 
| | to be updated. 
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Responses 

DMSACC723I mode (cuu) R/0 [-OS] 

The specified disk is attached to the CMS virtual machine in 
read-only mode. When the disk specified is in OS or DOS format, 
CMS adds the "-OS" to the response. 

DMSACC72UI cuul REPLACES mode (cuu2) 

Before execution of the command the disk represented by cuu2 was 
the "mode" disk. The disk, cuul, is now assigned that fileaode 
letter. This message is followed by message DMSACC726I. 

DMSACC725I cuu ALSO = •mode 1 [-OS] 

The disk specified by cuu is the "mode" disk and an ACCESS command 
was issued to assign it another filemode letter. When the disk 
specified is in OS or DOS format, CMS adds the -OS to the 
response . 

DMSACC726I • cuu mode' RELEASED 

The disk located at virtual address cuu that is being accessed as a 
read/write disk is already currently accessed. The effect of the 
previous ACCESS command is canceled and the disk is released from 
the virtual machine configuration. 



Qtilii£ Messages and Return Codes 

DMSACC002E FILE 'DMSROS TEXT" NOT FOUND RC=28 

DMSACC003E INVALID OPTION 'option* RC=24 

DMSACC017E INVALID DEVICE ADDRESS 'cuu' RC=24 

DMSACC048E INVALID MODE •mode' RC=24 

DMSACC059E 'cuu 1 ALREADY ACCESSED AS READ/WRITE 'mode* DISK RC=36 

DMSACC060E FILE (S) »fn [ft [fm]]' NOT FOUND. DISK 'mode (cuu)' WILL NOT 

BE ACCESSED RC=28 
DMSACC112S DISK 'mode(cuu)' DEVICE ERROR RC=100 
DMSACC113S mode (cuu) NOT ATTACHED RC=100 

DMSACC230W OS DISK - FILEID AND/OR OPTIONS SPECIFIED ARE IGNORED 
DNSACC240S ERROR LOADING READ OS ROUTINE 'DMSROS TEXT' 
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ASSEMBLE 



Use the ASSEMBLE command to invoke the Assembler to assemble the 
specified file. The Assembler processing and output are controlled by 
the options selected. The format of the ASSEMBLE command is: 



Assemble 



fn [ (options. . .[) ]] 
list ing control options; 

r ir-ir t r i 

IALOGIC | |ESD | | FLAG (nnn) | |LINECOUN (nn) | 
|NOALOGIC| |NOESD| I FLAG _[0l | ILINBCOUN J55H 

L JtJL JL ~~ J 



r t r t r i r t r t 

I LIST | IMCALL | |MLOGIC | |RLD | |LIBMAC | 

|HOLIST| IHOMCALLI |HOMLOGIC| |HORLD | |NOLIBMAC| 

L J L J L ~J t J L "" J 



r t r i 

IXBEF 1FULL1 | | PRINT | 

IXREF (SHORT) | |MOPRIMT| 

IHOXREF | I DISK | 

t j l"~ ~ J 



output control options; 



r t 

| DECK | 
1H0DBCK1 

L J 



r i 
| OBJECT | 
IHOOBJECTi 

L J 



r t 
| TEST | 
| HOT EST | 

L J 



SYSTERM options: 



r t 

IN0MBER1 
INONUM | 

L J 



r i 
I STMT | 
|NOSTMT| 

L J 



r t 

1 TERMINAL | 

IMOTERM "| 

L J 



other options; 

rir TTTT T 

IlilGH | IBDFSIZE (MIN) | | RENT | | SYSPARM (string) | 

|NOALIGN| IBDFSIZE (STD) 1 jNORENTI | SYSPARM (?) | 

•- J •- j l J | SYSPARM () j 

L J 



where 
fn 



is the filename of the source file to be assembled. The file 
must have a filetype of ASSEMBLE and fixed-length, 
80-character records. 



LISTING CONTROL OPTIONS: The list below describes the assembler options 
you can use to control the assembler listing. The default values are 
underscored. 



ALOGIC 



lists conditional assembly statements in open 
code. 
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NOALOGIC 



suppresses the ALOGIC option. 



ESD 



lists the external symbol dictionary (ESD) 



NOESD 



suppresses the printing of the ESD listing. 



FLAG (nnn) 
FLAG iOj_ 



does not include diagnostic messages and MNOTE 
messages below severity code nnn in the listing. 
Diagnostic messages can have severity codes of H, 
8, 12, 16, or 20 (20 is the most severe) ; and 
MNOTE severity codes can be between and 255. For 
example, FLAG (8) suppresses diagnostic messages 
with a severity code of 4 and MNOTE messages with 
severity codes of through 7. 



LINECOUN (nn) 
LINECOON J551 



nn specifies the number of lines to be listed per 
page. 



LIST 

NCLIST 

MCALL 



NOMCALL 



produces an assembler listing. 



does not produce an assembler listing. This option 
overrides ESD, RLD, and XREF. 

lists the inner macro instructions encountered 
during macro generation following their respective 
outer macro instructions. The assembler assigns 
statement numbers to these instructions. The MCALL 
option is implied by the MLOGIC option; NOMCALL 
has no effect if MLOGIC is specified. 

suppresses the MCALL option. 



MLOGIC 



lists all statements of a macro definition 
processed during macro generation after the macro 
instruction. The assembler assigns statement 
numbers to them. 



NOMLOGIC 



suppresses the MLOGIC option. 



RLD 



produces the relocation dictionary 
listing. 



as part of the 



NORLD 
LIBHAC 



does not print the relocation directory. 



lists the macro definitions 
libraries and any assembler 
the logical END statement, 
statement is the first END 
during macro generation. It m 
or in open code; it may 
substitution. The assembler 
numbers to the statements th 
END statement. 



read from the macro 

statements following 

The logical END 

statement processed 

ay appear in a macro 

even be created by 

assigns statement 

at follow the logical 
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HOLIBMAC 



suppresses the LIBMAC option. 



Mil llUliLL 



includes in the assembler listing a cross 
reference table of all symbols used in the 
assembly. This includes symbols that are defined 
but never referenced. The assembler listing also 
contains a cross reference table of literals used 
in the assembly. 



XREF (SHORT) 



includes in the assembler listing a cross 
reference table of all symbols that are referenced 
in the assembly. Any symbols defined but not 
referenced are not included in the table. The 
assembler listing contains a cross reference table 
of literals used in the assembly. 



HOXREF 



does not print the cross-reference tables. 



PRINT 
PR 



writes the LISTING file to the printer. 



NOPRINT 
NCPR 



suppresses printing the LISTING file. 



DISK 
DI 



places the LISTING file on a virtual disk, 



OUTPUT CONTROL OPTIONS: The output control options are used to control 
the object module output of the assembler. 



DECK 



writes the object module on the device specified 
on the FILEDEF statement for PUNCH. If this 
option is specified together with the OJBECT 
option, the object module is written both on the 
PUNCH and TEXT files. 



NODECK 



suppresses the DECK option. 



OBJECT 
OBJ 



writes the object module on the device specified 
in the TEXT FILEDEF statement. If this option is 
specified together with the DECK option, the 
object module is written on the two devices 
specified in the FILEDEF statement for TEXT and 
PUNCH. 



NOOBJECT 
NOOBJ 



does not create the object module. 



TEST 



includes the special source symbol table (SYM 
cards) in the object module. 



NOTEST 



Does not produce SYH cards. 



84 IBM VM/370: Command Language Guide for General Users 



ASSEMBLE 

SYSTERM OPTIONS: These are used to control the SYSTERM file associated 
vith your assembly. 

NUMBER writes the line number field (columns 73-80 of the 

HUM input records) in the SYSTERM listing for 

statements for which diagnostic information is 
given. This option is valid only if TERMINAL is 
specified. 

NONDM suppresses the NUMBER option. 

STMT writes the statement number assigned by the 

assembler in the SYSTERH listing for statements 
for which diagnostic information is given. This 
option is valid only if TERMINAL is specified. 

NOSTMT suppresses the STMT option. 

TERMINAL writes the diagnostic information on the 

TERM SYSTERH data set. The diagnostic information 

consists of the diagnosed statement followed by 

the error message issued. 

| NOTERH suppresses the TERHINAL option. 

OTHER ASSEHBLER OPTIONS; The options below allow you to specify various 
functions and values for the assembler. 

AllGN aligns all data on the proper boundary in the 

I kL§.l object module; for example, an F-type constant is 

aligned on a fullword boundary. In addition, the 
assembler checks storage addresses used in machine 
instructions for alignment violations. 

NCALIGN does not align data areas other than those 

| NOALGN specified in CCH instructions. The assembler does 

not skip bytes to align constants on proper 
boundaries. Alignment violations in machine 
instructions are not diagnosed. 

BUFSIZE (HIN) uses the minimum buffer sizes (790 bytes) for each 

of the utility data sets (SYSUT1, SYSUT2, and 
SYSUT3) . Storage normally used for buffers is 
allocated to work space. Because more work space 
is available, more complex programs can be 
assembled in a given virtual storage size; but the 
speed of the assembly is substantially reduced. 

BUFSIZE iSTD]_ chooses the buffer size that gives optimum 

performance. The buffer size depends on the amount 
of virtual storage. Of the assembler working 
storage in excess of minimum requirements, 37% is 
allocated to the utility data set buffers and the 
rest to macro generation dictionaries. 
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RENT checks your program for a possible violation of 

program reenterability. Code that makes your 

program nonreenterable is identified by an error 
message. 

H.QRENT suppresses the RENT option. 

SYSPARM /'(string) \ 'string 1 is the value assigned to the system 
() null f variable symbol SSYSPARM. The varible (string) 
string / cannot be greater than 8 characters. If you 
(?) ) wish to enter a string of more than 8 characters, 
use the SYSPARM (?) format. With the SYSPARM (?) 
| form, CMS prompts you with the message: 

| ENTER SYSPARM: 

| You can enter a string of characters up to the 

I option limit of 100 characters. You can also 

| enter parentheses and embedded blanks from the 

I terminal. SYSPARM () enters a null string of 

| characters. 

OVERRIDING CMS FILE DEFAULTS: When you issue the ASSEMBLE command, there 
are default FILEDEF commands issued for assembler data sets. You may 
want to override these with explicit FILEDEF commands. The ddnames most 
likely to be overridden are: 

ASSEMBLE (SYSIN input to the assembler) 

TEXT (SYSLIN output of the assembler) 

LISTING (SYSPRINT output of the assembler) 

PUNCH (SYSPUNCH output of the assembler) 

CMSLIB (SYSLIB input to the assembler) 

The default FILEDEF commands issued by the assembler for the ddnames 
are: 

FILEDEF ASSEMBLE DISK fn ASSEMBLE fm (RECFM FB LRECL 80 Block 800 

FILEDEF TEXT DISK fn TEXT fm 

FILEDEF LISTING DISK fn LISTING fm (RECFM FBA Block 1210 

FILEDEF PUNCH PUNCH 

FILEDEF CMSLIB DISK CMSLIB MACLIB * (RECFM FB LRECL 80 Block 800 

A FILEDEF command, issued for any of the above ddnames prior to 
invoking the assembler, overrides the default FILEDEF issued by the 
assembler. Assume that there is an assembler source file in card deck 
form which you want to assemble. If you have this card deck read into 
your virtual machine reader, you must issue an overriding FILEDEF 
command prior to assembling, that is, FILEDEF ASSEMBLE READER. Now you 
can invoke the assembler as follows: 

ASSEMBLE SAMPLE (options .... 

The name SAMPLE is used by the assembler as the filename for any TEXT 
or LISTING files produced by the assembler, provided a file SAMPLE 
ASSEMBLE does not exist on any accessed disk, in which case, the first 
file is erased. 
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Similarly, if you have a tape containing an assembler input file 
which you want to assemble, you must issue the following commands: 

FILEDEF ASSEMBLE TAPn (RECFM F LRECL 80 BLCCK 80 
or, if the file is blocked, 

FILEDEF ASSEMBLE TAPn (RECFM FB LRECL 80 ELOCK 80*n 
followed by 

ASSEMBLE SAMPLE (options .... 

You can use OS data sets as CMS files by defining those data sets 
with the FILEDEF command. For example, 

FILEDEF ASSEMBLE DISK MYDSET ASSEMBLE BU DSN OS DATASET 

where : 

B4 is the mode of OS disk to be accessed. 

OS. DATASET is the name of the OS data set to be used for input. 

To assemble this, issue: 

ASSEMBLE MYDSET 

The same examples used here for input files can be applied to other 
ddnames. Care should be taken that any attributes specified for the 
file conform to the assembler expected attributes for the device, that 
is, PUNCH, LRECL 80 BLOCK 80, TERMINAL 132. 

Messages and Return Codes 

For the messages and return codes associated with the ASSEMBLE command, 
see the OS/VS and VM/370 Assembler Programmer's Guide. 
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CMSBATCH 

CMSBATCH 

You use the CMSBATCH command to invoke the CMS Batch Facility. The 
format of the CMSBATCH command is: 



i 1 

| | CMSBATCH | [sysname] I 



i 



| sysname is the name of the saved system that the CMS Batch Facility 

| loads for all subsequent batch jobs. This operand can only be 

| used if the installation has set up the CMS Batch Facility as 

| a saved system. 

You issue this command immediately after loading CMS with the IPL 

command. You can find a complete description of the CMS Batch Facility 

in "Appendix C: Using the CMS Batch Facility" and in the VM/370: 
QE§E§tor^s Guide. 



J!£E2I Messages and Return Codes 

DMSBTB100E NO BATCH PROCESSOR AVAILABLE RC=40 

DMSBTB101E BATCH NOT LOADED RC= 88 

DMSBTP105E NO JOB CARD PROVIDED RC=None 

DMSBTP106E JOB CARD FORMAT INVALID RC=None 

DMSBTP107E CP/CMS COMMAND 'command, (device)' NOT ALLOWED RC=88 

DMSBTP108E /SET CARD FORMAT INVALID RC=None 

DMSBTP109E CPU | PRINTER | PUNCH LIMIT EXCEEDED RC=None 
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COMPARE 

Use the COMPARE command to compare two disk files of fixed or variable 
length format and to display the contents of corresponding unlike 
records at the terminal. The format of the COMPARE command is: 



i 1 

| COMpare | fileidl fileid2 [ (COL mm-nn[) ]] I 

i i 



where : 

fileid is the file identification of the two files to be compared. 
All three identifiers (filename, filetype, and filemode) 
must be specified for each fileid. 

Option 

(COL mm-nn) defines any contiguous portion of the corresponding 
(COL J— lreclj_ records for comparison. The comparison begins at 
position mm of each record in both files. The 
comparison proceeds up to and including position nn of 
each record in both files. If mm is not specified, the 
comparison starts with the first character of each 
record in both files. If nn is not specified, the 
default ending position is the last character of each 
record. The "— " is reguired and may not be preceded or 
followed by a blank. "lrecl" is the logical record 
length of the file. 

If you want to stop the displaying of the dissimilar records, use the 
CMS immediate command HT. 

Examples 

COMPARE ABC XYZ A1 ABC MNO A1 

Each record in file ABC XYZ A1 is compared with the corresponding record 
in file ABC MNO A1. Comparison begins at the first position of each 
record and proceeds for the entire length of the record. Records which 
do not match are displayed at the terminal. 

COMPARE MYFILE ASSEMBLE A1 YOURFILE ASSEMBLE A1 (COL 10-72) 

Positions 10 through 72 of each record in file MYFILE ASSEMBLE A1 are 
compared with corresponding positions of each record in file YOURFILE 
ASSEMBLE A1. Records in which these positions do not match are displayed 
at the terminal. 



Responses 

If corresponding records in each file do not match, the record from the 
first file is displayed, followed by the record from the second file. 
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IEE2E W®§§§5S§ §B<1 Return Codes 

DMSCHP002E FILE 'fn [ft [fa]]' HOT FOUND RC=28 

DMSCMP003E INVALID OPTION 'option' RC = 24 

DMSCMP005E NO 'option' SPECIFIED RC=24 

DMSCMP009E COLUMN 'col' EXCEEDS RECORD LENGTH RC=24 

DMSCMP010E PREMATURE EOF ON FILE [ ' f n ft [ f ■ ' ] ] RC=40 

DMSCMP011E CONFLICTING FILE FORMATS RC=32 

DMSCMP019E IDENTICAL FILEIDS RC=24 

DMSCMP029E INVALID PARAMETER 'param' IN THE OPTION 'col' FIELD RC=24 

DHSCMP054E INCOMPLETE FILEID SPECIFIED RC=2U 

DMSCMP062E INVALID * IN FILEID RC=20 

DMSCMP104S ERROR 'nn' READING FILE 'fn ft f m • FROM DISK RC=100 

DMSCMP209W FILES DO NOT COMPARE RC=H 
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COPYFILE 

Use the COPYFILE command to copy data from specified input files to the 
output files according to conversions and specifications indicated by 
the options selected. The manner in which the file identifiers are 
entered determines whether one output file is created (single output 
mode) or multiple files are created (multiple output mode) . 

The COPYFILE command is used to: 

• Copy one file to another 

• Combine two or more files into a single output file 

• Copy files into multiple output files 

• Copy a file from one minidisk to another 

With the COPYFILE command, you can: 

• Display the names of files copied at the terminal. 

• Replace the existing output files with the new output files. 

• Change the record format and logical record length * 

• Selectively copy records from the input f ile (s) based on either: 

- Record number 

- Label field of record 

• Remove the trailing fill characters from each record. 

• Compress an input file. 

• Convert 026 key punch characters to corresponding 029 characters. 

• Convert lowercase letters to uppercase and uppercase letters to 
lowercase. 

• Overlay data in an existing file with selected data from another 
file. 

• Append one file to another file. 

• Hove selected positions within each record to specified positions in 
the records of another file. 

• Insert a specified character string or hexadecimal character into 
selected positions of each record in the output file. 

• Perform character translations. 
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The format of the COPYFILE command is 



fileidil [ f ileidi2. . . ] [ f ileido ] [ (options. ..[)] ] 

options: 

r t r i r t 

IType | IHEWDatel | RECf m fP\\ [LHecl nn] 
IMQTYPel |OLDDate| | \VJ| 

L J L J L J 




r i r t r t 

IPRompt | |FRom recno | |FOR recno | 

JNOPRomptj JFRLabel xxxxxxxxj JTOLabel xxxxxxxx | 

L J L J C J 

r n r i r ir -\ 

ITROnc | |PAck | [EBcdic] |OPcase | I MEW File I 

|NOTRunc| |UMPack| |LOwcase| |REPlace| 

L J l j l j |OVly | 

| APpend | 

L J 

r i r i 

|FI11 c | |SPecs | [TRAns] 

| Fill hh| IMPS Pecs I 

|FI11 40 1 «- J 

L J 



w h er e : 

fileidil is the first (or only) input file. Each file identifier 

(filename, filetype and filemode) must be specified either 

by indicating the specific identifier or by coding an 

asterisk. However, all three file identifiers of fileidil 

cannot be specified by asterisks. 

fileidi2 is an additional input file(s). Each file identifier 
(filename, filetype, and filemode) must be specified. In 
single output mode, any of the three input file identifiers 
may be specified either by indicating the specific 
identifier or by coding an asterisk. However, all three 
file identifiers of fileidi2 cannot be specified by 
asterisks. In multiple output mode, an asterisk is an 
invalid file identifier. An equal sign (=) may be coded for 
any of the file identifiers, indicating that it is the same 
as the corresponding identifier in fileidl. 

fileido is the output f ile (s) to be created. Each file identifier 
(filename, filetype and filemode) must be specified. To 
create multiple output files, an equal sign (=) must be 
coded in one or more of the identifier fields. If there is 
only one input fileid, fileido may be omitted, in which case 
it defaults to = = = (the input file represented by fileidil 
is replaced) . 

The following options are the most used options of the COPYFILE 
command. Minor variations of these options are described in the "Other 
Options" section. 
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Op t ions 
TYPE 

HCTYPE 

NEWDATE 

OLDDATE 



displays at the terminal the names of the files being 
copied. 

suppresses the displaying at the terminal the names of 
the files being copied. 

uses the current date as the creation date of the new 
files. 

uses the date on the first input file as the creation 
date of the nev files. 



RECFM ( F I is the record format of the output files. If not 
j V | specified , the output record format is the same as that 
' > of the input. 

LRECL nn is the logical record length of the output file (s) if it 
is to be different from that of the input files. The 
maximum value of nn is 65535. 

PROMPT displays the messages which request specification or 
translation lists. 

NOPROMPT suppresses the display of prompting messages for 
specification and translation lists. 



Copy Extent Optio ns 



FROM recno is the starting record number for each input file in the 
copy operation. 

FRLABEL xxxxxxxx 

xxxxxxxx is a character sequence which appears at the 
beginning of the first record to be copied from each 
input file. Up to eight characters may be specified. 
The character sequence may not contain embedded blanks. 

FOR recno is the number of records to be copied from each input 
file. 

TOIABEL xxxxxxxx 

xxxxxxxx is a character sequence which, if at the 
beginning of a record, stops the copy operation for that 
input file. The record containing the given character is 
not copied. Dp to eight characters may be specified. 
The character sequence may not contain embedded blanks. 



Character Translation Options 



TRUNC 



removes trailing blanks (or fill characters) 
converting to RECFM V output file record format. 



when 



The RECFM and LRECL options can be used to specify the 
record format and logical record lengths of the output 
files being created. 
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There are two record foraats, F (fixed) or ? (variable) . 
All records in a fixed record format file are the saie 
size (for example, card image files, where all records 
are 80 bytes long) . Variable record format files have 
records of varying sizes. SCRIPT files, where the length 
of each record is usually different, are variable record 
format files. 

The logical record length (LRECL) applies only to fixed 
record format (F) files. For example, for card image 
files, the logical record length is 80. 

If the RECFH or LRECL options are not specified, the 
record format and logical record length for the output 
file are the same as for the current or only input file. 
If the output file record format is V, then the LRECL 
option (if specified) is ignored. 

When the output file record format is F, the input 
records are truncated or padded, as necessary, to the 
logical record length. When the output file record 
format is V, the input records are simply copied to the 
output file, unless the TRUHC option is specified. If 
TRUHC and RECFH V are specified, all blanks at the end of 
each record are removed before the record is written 
out. 

For information on variations of this option, see the 
discussion of the FILL option under "Other Options." 



HOTRUNC suppresses the removal of trailing blanks (or fill 
characters) when converting to RECFH V output file record 
format. 



PACK 



converts repetitively occurring characters to compressed 
format. If the FILL option is not used, all occurrences 
of two or more blanks in the file are encoded as one 
character, and four or more occurrences of any other 
character in the file are encoded as three characters. 
If a FILL character is specified, that character replaces 
the blank as the special packing character, and blanks 
are treated as any other non-fill character. 

Source files generally take up a great deal of disk 
space, because they contain many blanks. This is 
particularly wasteful in the case of source files which 
are seldom used. 

Use the PACK option of the COPTFILE command to encode a 
file so that multiple blanks are represented as a single 
character, and multiple occurrences of other characters 
also produce space savings. 

ihen the PACK option is used, the output file is in a 
format which can be decoded only by the UNPACK option of 
the COPTFILE command. 



For example, the command: 

COPTFILE * ASSEHBLE A1 (PACK 
causes all ASSEHBLE files on the A-disk to be packed. 
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If you know that a particular character occurs a great 
■any tiies in a file (and if this character occurs tore 
often than the blank character) , specify that character 
as the fill character for the file. Two or »ore 
occurrences of the specified fill character are encoded 
as one character. Then four or nore consecutive 
occurrences of any other character (including the blank) 
are encoded as three characters. 



However, not every file should be packed. In fact, if 
the file does not contain very many occurrences of 
■ultiple characters, it is possible for the packed file 
to be longer than the original file. 



CAPTI ON ; A file in packed fonat should not be modified 
in any way. If such a file is Modified in any way, the 
UNPACK routines will be unable to reconstruct the 
original file. Packed files should never be combined or 
split. 



UNPACK 



reverses the PACK operation. 



EBCDIC converts a file that was created with 026 keypunch 
characters (BCD) , to 029 keypunch characters (EBCDIC) . 
The following conversions are made: 



< 


to 


) 


& 


to 


♦ 


% 


to 


( 


# 


to 


s 


a 


to 


1 


• 


to 


• 



UPCASE converts all lowercase characters in each record to be 
written to an output file to uppercase before the record 
is written out. 

LOHCASE converts all uppercase characters in each record to be 
written to an output file to lowercase before the record 
is written out. 



Other Options 



In addition to the options 
offers several variations: 



already described, the COPTFILE coanand 



NEW FILE checks that output files did not previously exist. If 
one or more output files do exist, an error message is 
displayed and the COPTFILE coaiand terminates. This 
option is the default so that existing files are not 
inadvertently destroyed. 

REPLACE causes the output file to be replaced by an input file of 
the same name. REPLACE is the default option when the 
output file identification is n - - =* n 
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OVLY overlays the data in an existing output file with data 
froi the input file. 

APPEND appends the data from the input file to the end of a file 
specified by the output file identifiers. If no output 
file exists, one is created. 

FILL c is the padding and truncation character or the principal 

FILL hh packing character for the PACK option. The fill character 

FILL 40 aay be specified by entering a single character, c, or by 

entering a two-digit hexadecimal representation of a 

character. The default is 40 (the hexadecimal 

representation for a blank in EBCDIC) . 

When the output file record format is F, the input 
records are truncated or padded, as necessary, to the 
logical record length. The padding and truncation 
character is usually a blank, but this default may be 
overridden if you specify a new padding and truncation 
character with the FILL option. 

When BECFH V and TRDMC are specified, all blanks on the 
end of each record are removed before the record is 
written. To truncate some character other than blanks, 
use the FILL option. 

The PACK routine treats the blank as a "special packing 
character". If desired, the FILL option may be used to 
change the "special packing character" to a non-blank 
character. 



SPECS 



requests a user specification list defining the manner in 
which data is to be copied. 



If the SPEC'S option is 
prompting message: 



used, COPIFILE issues the 



DMSCPY601R EHTER SPECIFICATION LIST 



The - keyboard unlocks, 
specification list. 



and 



you may type in the 



The format of the specification list is: 

source target [source target] ... 

where source can be specified in several ways and target 
is a decimal number representing a position in the output 
record. Source can be specified as: 

• A pair of columns of the input file, specified in the 
format "nn-mm", two decimal number values separated by 
a hyphen. This format causes the specified positions 
in the input file record to be copied to the output 
file. For each record that is copied, the value of mm 
(the ending record position) is compared to the length 
of the record. Whenever the specified ending record 
position exceeds the length of the record, the end of 
the record becomes the assumed ending position for 
that record. For example, the source specification 
"23-40" causes columns 23 through 40 of the input file 
record to be copied to the output file. 
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• A string of characters, delimited by nonalphaieric 
characters. Such a specification causes the specified 
string of characters to be placed in the output file 
record. For example, a source specification of 
"/AbCd1234/" causes the string "AbCd1234" to be placed 
in each record of the output file. The letters in the 
string of characters are not automatically raised to 
uppercase; if you wish capital letters, you must type 
them in as such. 

• A string of characters, specified by the letter n H n 
followed by an even number of hexadecimal digits 
entered using numeric characters and either upper or 
lower case alphabetic characters. For example, the 
specification, n hb7c1ff M causes the characters given 
by the hexadecimal values X^BT 9 , X*C1«, and X'FF 1 to 
be placed in the output file. 

For example, consider the following specification list: 

1-5 10 /ABC/ 3 /XIZ/ 20 H00 25 

This specification list contains four sets of 
specifications, and causes data to be placed into the 
output record in the following manner: First, positions 
1 through 5 of the input record are placed in positions 
10 through 14 of the output record. Next, the characters 
"ABC" are placed in positions 3 through 5 of the output 
record. Next, the characters "XXZ" are placed in 
positions 20 through 22 of the output record. Finally, 
the character X'00' is placed in position 25 of the 
output record. 

For variable length output files, the length of the 
output record is determined by the position of the 
rightmost byte of data that was placed in the output 
record. For fixed length output files, the record is 
padded or truncated to the logical record length. 

Positions of the output record for which no data is 
specified are filled with blanks. Use the FILL option to 
specify another fill character. In the example shown 
above, positions 1-2, 6-9, 15-19 and 23-24 of the output 
file record contain blanks. In addition, if the output 
record format is F, positions 26 through to the end of 
the record contain blanks. 

The SPECS option is particularly useful in conjunction 
with the OVLY option. If these options are used 
together, the specification list indicates the exact 
positions of the output file record to be overlaid. For 
example, if the specification list 1-10 20 is used with 
the OVLT option, then positions 1-10 of each input file 
record overlay positions 20-29 of each record of the 
existing output file, and the other positions of the 
output file records remain unchanged. 

The specification list can be continued onto additional 
lines by typing •+♦• at the end of the first line. If 
these two characters are encountered when a 
source-specification is expected, all scanning of that 
line ceases, and the keyboard unlocks so that a new line 
may be entered. 



Section 7: Format and Usage Rules for CHS Commands 97 



COPYFILE 

NOSPECS indicates that no specification list is to be entered. 

TRAMS specifies that you are to be asked for a list of 
character translations to be made as the file is copied. 

The TRANS option allows you to specify your own list of 
translations; it overrides any of the other three 
translation options (UPCASE, LOMCASE or EBCDIC). 

When the TRAMS option is specified, the COPYFILE command 
displays the prompting Message: 

DMSCPY602R EMTER TRANSLATION LIST 

You lay then enter the translation list. 

The translation list consists of a series of pairs of 
characters, separated by blanks. Each character may be 
specified either by entering the character itself or by 
entering a two-digit hexadecimal eguivalent (the latter 
is particularly useful for characters not available on 
your terminal keyboard) • 

For example, the translation list: 

* - A fO 00 ff 

specifies that the character '*' is to be translated' to 
•-•, the character •A 1 is to be translated to X^FO 1 , and 
the character X'00» is to be translated to I'FF'. If the 
preceding translation list is specified in conjunction 
with the LOHCASE option, then the translation 'A' to 
X»F0» overrides the LOWCASE translation, 'A 1 to 'a*. 

The translation list can be continued onto additional 
lines by typing •♦♦• as the last two characters of the 
present line. Whenever these two characters are 
encountered when the first character of a character pair 
is expected, all scanning of that line ceases, (for 
typewriter terminals, the keyboard unlocks) , then a new 
line may be entered. 



Incompatible Options 

Figure 14 shows combinations of options which should not be specified 
together in the same COPYFILE command. 

If the option in the first column is specified, none of the options 
in the second column can be coded. < 
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Option 


Incompatible Options | 


APPEND 


| LBECL, NEWDATE, NEWFILE, OLDDATE, OVLY, PACK, BECFH, | 




! BEPLACE, UNPACK | 


EBCDIC 


PACK, UNPACK | 


FOB 


| PACK, TOLABEL, UNPACK | 


FBLABEL 


| FBOH, PACK, UNPACK | 


FBOH 


! FBLABEL, PACK, UNPACK | 


LOWCASE 


PACK, UNPACK | 


LBECL 


| APPEND, PACK, UNPACK | 


HEWDATE 


APPEND, OLDDATE j 


HER FILE 


I APPEND, OVLY, BEPLACE | 


HOPBOHPT 


PBOHPT I 


NOSPECS 


| PACK, SPECS, UNPACK | 


HOTBUHC 


PACK, TBUNC, UNPACK j 


HOTYPE 


TYPE | 


OLDDATE 


APPEND, NEWDATE I 


OVLY 


APPEND, NEWFILE, PACK, BEPLACE, UNPACK | 


PACK 


APPEND, EBCDIC, FOB, FBLABEL, FBOH, LOWCASE, LBECL, | 




OVLY, BECFM, SPECS, TOLABEL, TBANS, TBUNC, UNPACK, | 




UPCASE ) 


PBOHPT 


HOPBOMPT I 


BBCFH 


APPEND, PACK, UNPACK | 


BEPLACE 


APPBND, NERFILE, OVLY | 


SPECS 


NOSPECS, PACK, UNPACK | 


TOLABEL 


FOB, PACK, UNPACK | 


TBAHS 


PACK, UNPACK I 


TBDIC 


NOTBUNC, PACK, UNPACK | 


TYPE 


NOTYPE I 


DMPACK | 


APPBND, EBCDIC, FOB, FBLABEL, FBOH, LOWCASE, LBECL, | 




OVLY, PACK, BECFH, SPECS, TOLABEL, TBANS, TBUNC, | 




UPCASE I 


DPCASE 


PACK, UNPACK 1 



Figure 14. COPYFILE Option Incompatibilities 



COPYFILE OLD FILE Al NEW FILE A1 
Copies the file OLD FILE A1 to a new file named NEW FILE A1. 

COPYFILE * FILB A1 BIG FILE A1 

Copies all files with filetype of FILE and filemode of A1 and combines 
them into a single output file named BIG FILE A1. If the files A FILE 
A1, B FILE Al, and C FILE A1 exist, they are copied to BIG FILE A1 and 
are not erased. 

COPYFILE OLD * B1 NEW * B1 

Copies a group of files, each with a filename of OLD and a filemode of 
B1, to a new group of files each with a filename of NEW and a filemode 
of B1. If the files named OLD NAHE B1, OLD BIBTBDA B1, and OLD ADDBESS 
B1 exist, they are copied to files named NEW NAHE B1, NEW BIBTHDA B1, 
and NEW ADDBBSS B1, respectively. 
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COPTFILE X Y A1 P Q A1 BIG FILE A1 

Combines files X I A1 and F Q 11 in a single output file named BIG FILE 
A1. 

C0PYFI1B X * A1 = FILE = 

Combines all files with a filename of X and a filemode of A1 in a single 
output file named X FILE A1. 

COPYFILE X * A1 - T A1 BIG FILE A1 

Combines all files having a filename X and filemode A1 with the file 
having a filename X, a filetype T, and filemode A1 to form a single file 
named BIG FILE A1. The command 

COPYFILE X * A1 = T = BIG FILE = 

produces the same result. 

COPYFILE X * A1 P Q A1 BIG = A1 

Combines each file with a filename of X and a filemode of A1 with the 
file P Q A1 to create a file named BIG * A1. One file is created for 
each existing file with a filename X and filemode A1. 

COPYFILE X * A1 P = A1 BIG = A1 

Combines each file with a filename of X and a filemode of A1 with a file 
with a filename of P, a filemode of A1 and a filetype corresponding to 
that of the first input file; to produce a file with a filename of BIG, 
a corresponding filetype, and a filemode of A1. 

COPYFILE X * A1 P * = BIG = = 

produces the same result. 

COPYFILE BIGHAHE A A1 XYZ= == = 
Copies the file BIGHAHB A A1 to a file named XYZBIGHA AA A1. 

COPYFILE A B A1 C D A1 (FROM 10 FOR 25) 

Copies 25 records from file A B A1 to file C D it, beginning with the 
tenth record of i B 11. 

COPYFILE OLD B A1 NEW B A1 (FRLABEL BYPROG TOLABEL FIHIS) 

Copies records from file OLD B A1 to HEW B A1, beginning with a record 
containing the characters • HYPROG' and continues until a record 
containing the characters 'FIHIS* is encountered. 

COPYFILE * ASSEMBLE * (PACK 
Converts all files with a filetype of ASSEMBLE to packed format. 
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COPYFILB MY PILE A1 YODR FILE A1 (SPECS 

Copies the file named MY FILE A1 to a new file named YOUR FILE A1 
■odified according to the specification list. The message 

DMSCPY601H ENTER SPECIFICATION LIST 

is displayed. 

For example, if you enter the following specification list: 

.5 iv /ABC/ J QUU I 

Positions 1 through 5 of the input record are copied to positions 10 
through 14 of the output record, the character string "ABC is placed in 
positions 3 through 5 of the output record, and the character X'00' is 
placed in the first position of the output record. All other positions 
in the output record contain blanks unless a FILL character is 
specified, in which case the FILL character is placed in all unspecified 
positions. 

COPYFILE OLD FORM A1 NEW FORM A1 (SPECS OVLY 

Portions of the existing output file are to be overlaid by portions of 
the input record, or by character strings specified in a specification 
list. 

COPYFILE XYZ TEXT C = » A 
Copies a file from one virtual disk to another. 



Responses 

DHSCPY601R ENTER SPECIFICATION LIST: 

This messaqe reguests the specification list which is to be entered 
in conjunction with the SPECS option. 

DHSCPY602R ENTER TRANSLATION LIST: 

This message reguests the translation list which is to be entered 
in conjunction with the TRANS option. 

DMSCPY721I COPY 'fn ft fm' {TO |APPEND| OVLY} • f n ft fm» {0LD|NEW} FILE 

This message appears in conjunction with the TYPE option. It 
indicates the names of the input file and output file. 



Ot her Messages and Return Codes 

DMSCPY002E { INPUT |OVBRLAY } FILE 'fn ft fm' NOT FOUND RC=28 

DHSCPY003E INVALID OPTION 'option 1 RC=24 

DMSCPY024B FILE • f n ft fm' ALREADY EXISTS — SPECIFY 'REPLACE' RC=28 

DHSCPY029E INVALID PARAMETER 'parm' IN THE OPTION 'option' FIELD RC=24 

DMSCPY030E FILE • f n ft fm« ALREADY ACTIVE RC=28 
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DMSCPY037E DISK •■ode' IS READ/ONLY RC=36 

DMSCPY042E HO PILEID[ (S) ] SPECIFIED RC=2<* 

DMSCPY048E INVALID MODE •■ode' RC=2<4 

DMSCPY054E INCOMPLETE FILEID • f n [ft'] SPECIFIED RC=24 

DMSCPY062E INVALID CHAR •[ =| * | char ] • IN FILEID »[fn ft fm]' RC=20 

DMSCPY063E HO { TRANSLATION! SPECIFICATION } LIST ENTERED RC=U0 

DMSCPY064E INVALID [TRANSLATE] SPECIFICATION AT OR NEAR • • 

RC=2U 
DMSCPY065E 'option 1 OPTION SPECIFIED TNICE RC=24 
DMSCPY066E 'option* AND 'option 1 ARE CONFLICTING OPTIONS RC=2U 
DMSCPY067E COMBINED INPDT FILES ILLEGAL NITH PACK OR UNPACK OPTIONS 

RC=24 
DMSCPY068E INPDT FILE 'fn ft fi' NOT IN PACKED FORMAT RC=32 

DMSCPY101S 'SPECS' TEMP STRING STORAGE EXHAUSTED AT • • RC=88 

DMSCPY102S TOO MANY FILEIDS RC=88 

DMSCPY103S NUMBER OF SPECS EXCEEDS MAX 20 RC=88 

DMSCPY156E 'FROM nnn' NOT FOUND —FILE »fn ft f m • HAS ONLY 'nnn' RECORDS 

RC = 32 
DMSCPY157E LABEL 'label' NOT FOUND IN FILE 'fn ft f a • RC=32 
DHSCPY172E TO LABEL 'label' { EQUALS | IS AN INITIAL SUBSTRING OF} FRLABEL 

'label' RC=24 
DMSCPY173E NO RECORDS WERE COPIED TO OUTPUT FILE ' f n ft fm' RC=40 
DMSCPY901T UNEXPECTED ERROR AT 'addr' : PLIST 'plist' AT 'addr', BASE 

•addr', EC »nn' RC=256 
DMSCPY903T IMPOSSIBLE PHASE CODE 'hh» RC=256 
DHSCPY904T UNEXPECTED UNPACK ERROR AT 'addr' , BASE 'addr' RC=256 



102 IBM VM/370: Command Language Guide for General Users 



CP 



CP 

Use the CP command to transmit commands to the VH/370 control program 
environment without leaving the CHS environment. The format of the CP 



I 1 

| CP I [ commandline ] | 

I ; J 



where; 

commandline is any CP command permitted for your CP command privilege 
class. If this field is omitted, you are placed in CP 
mode and may enter CP commands without preceding each 
command with CP. To return to CHS issue the CP command 
BEGIN. 



Responses 

All responses are from the CP command which was issued. 

Example: 

CP TERMINAL LINESIZE 80 
The TERMINAL command is passed to the control program for processing. 
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DDR 

Ose the DASD Dump Restore (DDR) service program to dump, restore, copy, 
or print VM/370 user Minidisks. The DDR program may run as a standalone 
program, or under CHS via the DDR command. 

The DDR program has five functions: 

1. Dumps part or all of the data from a DASD device to tape. 

2. Transfers data from tapes created by the DDR DUMP function to a 
direct access device. The direct access device must be the same as 
that which originally contained the data. 

3. Copies data from one device to another of the same type. Data may 
be reordered, by cylinder, when copied from disk to disk. In order 
to copy one tape to another, the original tape must have been 
created by the DDR DUMP function. 

4. Prints selected parts of DASD and tape records in hexadecimal and 
EBCDIC on the virtual printer. 

5. Displays selected parts of DASD and tape records in hexadecimal and 
EBCDIC on the terminal. 

Note: To generate the VM/370 starter system from the distribution tape, 
the standalone RESTORE function must be used. 

The format of the DDR command is: 

i 1 

II r i I 

| DDR | [filename [filetype |filemode| ] ] I 

II 1*1 I 

II L J I 

i i 

where: 

filename filetype [filemode] is the identification of the file 

containing the control statements for the 
DDR program. If no file identification is 
provided, the DDR program attempts to 
obtain control statements from the 
console. The filemode defaults to * if a 
value is not provided. 

| Note: If you use the CMS DDR command, CMS ignores the SYSPRINT control 
| statement and directs the output to the CMS printer 00E. 



DDR CONTROL STATEMENTS 

Control statements describe the intended processing and the needed I/O 
devices. I/O definition statements must be specified first. 

All control statements may be entered from either the console or the 
card reader. Only columns 1 to 71 are inspected by the program. All 
data after the last operand in a statement is ignored. An output tape 
must have the DASD cylinder header records in ascending seguences; 
therefore, the extents must be entered in seguence by cylinder. Only 
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one type of function — dump, restore, or copy — nay be performed in one 
execution, but up to 20 statements describing cylinder extents may be 
entered. The function statements are delimited by an input or output 
statement, or by a null line if the console is used for input. If 
additional functions are to be performed, the sequence of certain 
control cards must be repeated. Only those statements needed to 
redefine the I/O devices are necessary for subsequent steps. All other 
I/O definitions remain the same. 

To return to CHS, enter a null line (carriage return) in response to 
the prompting message (ENTER:). To return directly to CP, key in #CP. 

The PRINT and TYPE statements work differently from other DDR control 
statements in that they operate on only one data extent at a time. If 
the input is from a tape created by the dump function, it must be 
positioned at the header record for each step. The PRINT and TYPE 
statements have an implied output of either the console (TYPE) or system 
printer (PRINT) . Therefore, PRINT and TYPE statements need not be 
delimited by an input or output statement. 



I/O DEFINITION STATEMENTS 



The I/O definition statements describe the tape, DASD, and printer 
devices used while executing the DASD Dump Restore program. 



INPDT/OOTPOT Control Statement 



An INPUT or OUTPUT statement describes each tape and DASD unit used, 
The format of the INPUT/OUTPUT statement is: 



INput | cuu type |volser| [(options...)] 
OUTput | jaltapej 

L J 

Options: 

r i r i r t 

|SKip nn| |H0de 6250 | |REWind | 

|SKi£ | |MOde 1600| lUNloadl 

i J | MOde 800| |LEave | 

L J L J 



where; 
| INPUT 
| OUTPUT 

cuu 

I type 
I 



indicates that the device described is an input device. 

indicates that the device described is an output device. 

is the unit address of the device. 

is the device type (2314, 2319, 3330, 3330-11, 3340-35, 
3340-70, 2305-1, 2305-2, 2400, 2420, or 3420) (no 7-track 
support for any tape devices) . Specify a 3410 device as a 
3420, a 3340-70F as a 3340-70, and a 3333 as a 3330. 
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volser 



altape 



Options 

SKIP nn 




Note: The DASD Dump Restore (DDR) program, running in a 
virtual machine, uses I/O DIAGNOSE 20 to perform I/O 
operations on tape and DASD devices. DDR under CHS requires 
that the device type entered agree with the device type of the 
real device as recognized by VH/370. If there is a conflict 
with device types, the following message is issued: 

DHKDDR701E INVALID OPTION 

However, if DDR runs standalone in a virtual machine, DDR uses 
DIAGNOSE 20 to perform the I/O operation if the device types 
agree and SIO if the device types do not agree. 

is the volume serial number of a DASD device. If the keyword 
•SCRATCH 1 is specified instead of the volume serial number, no 
label verification is performed. 

is the address of an alternate tape drive. 

Note: If multiple reels of tape are reguired and "altape" is 
not specified, DDR types the following at the end of the reel: 
"END OF VOLOHE CYL XXX HD XXX, MOUNT MOUNT NEXT TAPE." After 
the new tape is mounted, DDR continues automatically. 



forward spaces nn files on the tape, nn is any number up to 
255. The SKIP option is reset to zero after the tape has been 
positioned. 



MODE 6250 causes all output tapes that are opened for the first time 

| MODE 1600 and at the load point to be written or read in the specified 

MODE 800 density. All subsequent tapes mounted are also set to the 

specified density. If no mode option is specified, then no 

| mode set is performed and the density setting remains as it 

previously was. 

REWIND rewinds the tape at the end of a function. 

UNLOAD rewinds and unloads the tape at the end of a function. 

LEAVE leaves the tape positioned at the end of the file at the end 
of a function. 



SYSPRINT Control Statement 



Use the SYSPRINT control statement (in the standalone application only) 
to describe the printer that is to print data extents specified by the 
PRINT statement. It also can print a map of the cylinder extents from 
the DUMP, RESTORE, or COPY statement. If the SYSPRINT statement is not 
provided, the printer assignment defaults to 00E. CHS ignores the 
SYSPRINT statement when you invoke DDR as a command under CHS, and CHS 
always directs the output to 00E. The format of the SYSPRINT control 
statement is: 



| SYsprint | cuu 

i 



-j 




specifies the unit address of the device, 
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Function Statements 



The function statements tell the DDR program what action to perform. 
The function commands also describe the extents to be dumped, copied, or 
restored. The format of the DUMP/COPT/RESTORE control statement is: 



DUmp 
COpy 

BFstnre 



| |cyl1 [To] 

| |CPvol 

j {ALL 

j |' NUcleus 



[cyl2 [Reorder] [To] [cyl3]] | 

I 



where 

DUMP 



requests the program to move data from a direct access volume 
onto a magnetic tape or tapes. The data is moved cylinder by 
cylinder. Any number of cylinders may be moved. The format 
of the resulting tape is: 



Record J: a volume header record, consisting 
describing the volumes. 



of data 



Record 2: a track header record, consisting of a list of count 
fields to restore the track, and the number of data records 
written on tape. After the last count field the record 
contains key and data records to fill the 4K buffer. 

!§£°.E£l 3: track data records, consisting of key and data 
records packed into 4K blocks, with the last record 
truncated. 

Record 4: either the end— of— volume or end-of-job trailer 
label. The end volume label contains the same information as 
the next volume header record except that the ID field 
contains EOV. The end— of— job trailer label contains the same 
information as record 1 except that the cylinder number field 
contains the disk address of the last record on tape and the 
ID field contains EOJ. 

COPY requests the program to copy data from one device to another 
device of the same or equivalent type. Data may be recorded 
on a cylinder basis from input device to output device. A 
tape-to— tape copy can be accomplished only with data dumped by 
this program. 

| RESTORE requests the program to return data that has been dumped by 

| this program. Data can be restored only to a DASD volume of 

j the same or equivalent device type as it was dumped from. It 

| is possible to dump from a real disk and restore to a minidisk 

| as long as the device types are the same. 

| cyll [TO] [cyl2 [REORDER] [TO] [cyl3]] 

| Only those cylinders specified are moved, starting with the 

| first track of the first cylinder (cyll) , and ending with the 

I last track of the second cylinder (cyl2) . The REORDER operand 

| causes the output to be reordered, starting at the specified 

I cylinder (cyl3) or at the starting cylinder (cyll) if "cylS" 

| is not specified. The REORDER operand must not be specified 
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| unless specified limits are defined for the operation; the 

| starting and, if required, ending cylinders (cyll and cyl2) 

| must be specified. 

| CPVOL specifies that cylinder and all active directory and 

I permanent disk space are to be copied, dumped, or restored. 

| This indicates that both source and target disk must be in CP 

I format, that is, the CP Format/Allocate service program must 

| have formatted them. 

ALL specifies that the operation is to be performed on all 
cylinders. 

HDCLEOS specifies that record 2 on cylinder 0, track and the nucleus 
cylinders will be dumped, copied, or restored. 

Restrictions : 

1 . Each track must contain a valid home address, containing the real 
cylinder and track location. 

2. Record zero must not contain more than eight key and/or data 
characters. 

3. Flagged tracks are treated just as any other track for all 2314, 
2319, and 2305 devices. That is, no attempt is made to substitute 
the alternate track data when a defective primary track is read. 
In addition, tracks are not inspected to determine whether they 
were previously flagged when written. Therefore, volumes 
containing flagged tracks should be restored to the same cylinders 
of the volume from which they were dumped. The message DHKDDR715E 
occurs each time a defective track is dumped, copied or restored, 
and the operation continues. 

4. Flagged tracks for a 3330 device are handled automatically by the 
control unit and may never be detected by the program. The program 
may detect a flagged track if, for example, no alternate track is 
assigned to the defective primary track. If a flagged track is 
detected by the program, message DMKDDR715E occurs and the 
operation terminates. 

Example: 

INPUT 191 3330 STSRES 

OUTPUT 180 2400 181 (MODE 800 

SYSPRIHT OOF 

DUMP CPVOL 

INPUT 130 3330 HINI01 

DUMP 1 TO 50 REORDER 51 

60 70 101 

This example sets the density to 800 bpi, then dumps all pertinent 
data from the volume labeled • SYSRES* onto the tape that is mounted on 
unit 180. If the program runs out of room on the first tape, it 
continues dumping onto the alternate device (181) . While dumping, a map 
of the dumped cylinders is printed on unit OOF. When the first function 
is complete, the volume labeled 'HINI01* is dumped onto a new tape. Its 
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cylinder header records are labeled 51 to 100. A nap of the dumped 
cylinders is printed on unit OOF. Next, cylinders 60 to 70 are dumped 
and labeled 101 to 111. This extent is added to the cylinder map on 
unit OOF. When the DDR processing is complete, the tapes are unloaded 
and the program stops. 

If cylinder extents are being defined from the console, the following 
is displayed: 

ENTER CYLINDER EXTENTS 
ENTER: 

For any extent after the first extent, the message 

ENTER »EXT EXTENT OR NULL LINE 
ENTER: 

is displayed. 

You may then enter additional extents to be dumped, restored, or 
copied. A null line causes the job step to start. 



PRINT/TYPE Function Statement 

Use the PRINT and TYPE function statement to print or type (display) a 
hexadecimal and EBCDIC translation of each record specified. The input 
device must be defined as direct access or tape. The output is directed 
to the system console for the TYPE function, or to the SYSPRINT device 
for the PRINT function. (This does not cause redefinition of the output 
unit definition.) The format of the PRINT/TYPE control statement is: 



i ■ — 1 

| PRint | cyll [hh1 [rr1]] [To cyl2 [hh2 [rr2 ]]] [(options)] | 
I Tlpe | I 

i i options : ( 

I | [Hex] [Graphic] [Count] | 

i » 

where: 

cyll is the starting cylinder. 

hh1 is the starting track. If present, it must follow the cyll 
operand. The default is track zero. 

rr1 is the starting record. If present, it must follow the hh1 
operand. The default is home address and record zero. 

[TO] cyl2 is the ending cylinder. If more than 1 cylinder is to be 
printed or typed "TO cyl2 N must be specified. 

hh2 is the ending track. If present, it must follow the cyl2 
operand. The default is the last track on the ending 
cylinder. 

rr2 is the record ID of the last record to print. The default is 
the last record on the ending track. 
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O ption s: 

HEX prints or displays a hexadecimal representation of each record 
specified. 

GRAPHIC prints or displays an EBCDIC translation of each record 
specified. 

COUNT prints or displays only the count field for each record 
specified. 



Examples : 

PRIHT TO 3 

Prints all of the records from cylinders 0, 1, 2, and 3. 
PRIHT 1 3 

Prints only one record, from cylinder 0, track 1, record 3. 

PRIHT 1 10 3 TO 1 15 U 

Prints all records starting with cylinder 1, track 10, record 3, 
and ending with cylinder 1, track 15, record 4. 

The example in Figure 15 shows the information displayed at the 
console (TYPE function) or system printer (PRIHT function) by the DDR 
program. The listing is annotated to describe some of the data fields. 



Responses 



DMKDDR711R VOLID READ IS VOlid2 [HOT volidl] 

DO TOU WISH TO COHTIHOE? RESPOHD YES HO OR REREAD: 

where: 

volid2 is the volume serial number from the V0L1 label on the 
DASD unit. 

volidl is the volume serial number from the IHPDT or OUTPUT 
control card. 

The volume serial number read from the device at cuu is not the 
same as that specified on the IHPUT or OUTPUT control card. 

DMKDDR716R HO VOL1 LABEL FOUHD FOR volser 

DO YOU WISH TO COHTIHUE? RESPOHD YES HO OR REREAD: 

w her e: 

volser is the volume serial number of the DASD device from the 
IHPUT or the OUTPUT control card. 

The DASD device at cuu contains no volume serial number. 
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Home Address- 
Record 



1st Half of - 
Record 2 



Home Address 
Record 

2nd Half of 
Record 2 



CYL 019 HD 00 I HOME ADDRESS 0000130000 IRECORD ZERO 0013000000 



Cylinder and head 
identification for 
Record 



Home Address of track 
in hexadecimal format 



Record ID from the 
count field 




^- |CYL Uia l-IL) UU Ktl UUI j 




If the data length field is not zero I 

A heading is printed containing the I 

data length from the count field first in I 
decimal, then in hexadecimal 

The data is then printed in hexadecimal I 
with graphic interpretation to the right 

(not shown here). I 



04096 1000 DATA LENGTH -* 



00000 0000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 
SUPPRESSED CHARACTERS SAME AS ABOVE . . . 



CYL 019. HD 00 REC 002 COUNT 0013000002 00 I09A8 



02472 |09A8| DATA LENGTH 



Note: Data Length field repeated 
in heading. 



00000 0000 00000000 00000000 00000000 oooooooo oooooooo 00000000 00000000 00000000 
SUPPRESSED CHARACTERS SAME AS ABOVE . . . 



ABOVE RECORD WRITTEN USING RECORD OVERFLOW 



!•" 



This statement indicates that this portion i 
of Record 2 was written using the Write I 

Special Count, Key, and Data command. The 
remainder of Record 2 is found on the next I 
track as the first record after Record 0. 

I 



CYL 019 HD 01 HOME ADDRESS 0000130001 RECORD ZERO 0013000100 00 0008 OOOOOOOO OOOOOOOO 

■CYL 019 HD 01 REC 002 COUNT 0013000102 00 0658-* 

01624 0658 DATA LENGTH 

00000 0000 OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO oooooooo 
SUPPRESSED CHARACTERS SAME AS ABOVE . . . 



e 



CYL 019 HD 01 REC 003 COUNT 0013000103 80 0F80 
00128 0080 KEY LENGTH-* 




If the key length field is not zero 

» A heading is printed containing the key length 
first in decimal, then in hexadecimal. 
The key is then printed in hexadecimal with 
graphic interpretation to the right (not shown here). 



00000 0000 oooooooo oooooooo oooooooo oooooooo oooooooo oooooooo oooooooo oooooooo 

SUPPRESSED CHARACTERS SAME AS ABOVE . . . 
03968 OF 80 DATA LENGTH 

00000 0000 OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO oooooooo oooooooo 
SUPPRESSED CHARACTERS SAME AS ABOVE . . . 



CYL 019 HD 01 REC 004 COUNT 0013000104 00 0000 
END OF FILE RECORD- 



© 



Whenever the data length field is zero I 

an end-of-file prints next. I 



Figure 15. in Annotated Sample of Output froi the TYPE 
Functions of the DDR Program 



and PRIHT 
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DMKDDR717R DATA DUMPED FROM volidl TO BE RESTORED TO Volid2 

DO TOU WISH TO COHTINOE? RESPOND TES NO OR REREAD: 

wher e: 

volidl is the volume serial number from the input tape header 
record (volume duaped) . 

volid2 is the volume serial number from the output DASD device. 

The above message is printed to verify the input parameters. 

ENTER CYLINDER EXTENTS 
ENTER: 

This message is received only if you are entering input from your 
terminal. 

END OF VOLUME CYL XXX HD XX, MOUNT NEXT TAPE 

DDR continues processing, after the mounting of the next tape 
reel. 



where: 

volser is the volume serial number of the disk dumped. 

The RESTORE operation has begun. 

COPYING volser 
where: 

volser is the volume serial number described by the input unit. 
The COPY operation has begun. 

DUMPING volser 
where : 

volser is the volume serial number described by the input unit. 
The dumping operation has begun. 

PRINTING volser 
where: 

volser is the volume serial number described by the input unit. 
The PRINT operation has begun. 

END OF DUMP 

The DUMP operation has ended. 

112 IBM VM/370: Command Language Guide for General Users 



DDR 



END OF RESTORE 

The RESTORE operation has ended. 

END OF COPY 

The COPY operation has ended. 

END OF PRINT 

The PRINT operation has ended. 

END OF JOB 

All specified operations have completed, 



ENTER: 



Prompts input from the terminal. A null line (Enter key or 
equivalent) causes control to return to CMS, if the virtual machine 
is in the CMS environment. 
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DEBUG 

Use the DEBUG command to acquire online facilities for debugging 
programs running under CMS and to acquire an entry in CMS for handling 
external interrupts, program interrupts, and unrecoverable errors. The 
subcommands which may be issued in the DEBUG environment allow you to 
examine and change the contents of certain control words and registers 
as well as portions of virtual storage. The facilities of DEBUG are 
made available when: 

• The DEBUG command is issued 

• An external interrupt occurs 

• A break point (instruction address stop) is encountered during 
program execution; this causes a program interrupt. 

Once the DEBUG environment has been entered due to any of the above 
circumstances, you are in the DEBUG environment. Only DEBUG subcommands 
are valid input in this environment. 

When the DEBUG environment is entered, the contents of all general 
registers, the channel status word, and the channel address word are 
saved so they may be examined and changed before being restored when 
leaving the DEBUG environment. If DEBUG is entered via an interrupt, 
the old program status word for that interrupt is also saved. If DEBUG 
is the first command entered after an ABEND occurs, the contents of all 
general registers, the CSW, the CAW, and the old PSW are available from 
the time of the ABEND. The format of the DEBUG command is: 



i 1 

| DEBUG | | 

i i 



Notes : 

| 1. The CMS commands HB, HO, HT, RO, RT and SO are not recognized in 
the DEBUG environment. 

2. The floating— point registers cannot be examined or changed in the 
DEBUG environment. 

Responses 
None. 

D_EBUG SUBCOMMANDS: For a complete description of the DEBUG subcommands 
refer to the VM/370: System Programmer's Guide. Figure 16 summarizes 
the DEBUG subcommands. 
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r - — - - — ■ 1 

| Subcommand Format | Function | 


| BBeak id (symbol) | Stops program execution at the | 
I (hexloc/ |specified breakpoint. | 


| CAW IDisplays the contents of the | 
| | Channel Address Word at the time | 
| IDBBOG was entered. j 


| CSW IDisplays the contents of the | 
| | Channel Status Word at the time j 
| | DEBUG was entered. j 


| r i | Assigns a symbolic name to the | 
| DEFine symbol hexloc | n j | virtual storage address. | 
i 1 H 1 1 1 
1 L J 1 i 


lr r n |Dumps the contents of specified j 
| DUmp (symbol 1 |symbol2|| [ident] |virtual storage locations to the | 
I Ihexlod |hexloc2|| |virtual spooled printer. | 
I I I * II I I 

| L t JJ | | 


| r i | Returns to the CHS environment and) 
| GO | symbol | I starts execution at the specified | 
I | hexloc | llocation. I 

| L J | | 


I GFB regl [reg2] IDisplays the contents of the | 
j | specified general registers. j 


j HX IBeturns to the CMS command envi— j 
| Ironment. j 


| x i | Specif ies the base address to be j 
I OBigin | symbol | | added to locations specified in j 
| |hexloc| | other DEBUG subcommands. | 

| L J | | 


j PSW j Displays the contents of the old j 
| | Program Status Word. | 


| RETurn |Exits from DEBUG environment to j 
j |the CHS command environment. j 


| SET / CAW hexinfo \ | Changes the contents of specified | 
| ) CSW hexinfo [hexinfo] { (locations or registers. | 
| \ PSW hexinfo [hexinfo] ? | I 
| ' GPB reg hexinfo [ hexinfo ] ) I 1 


| STore ( symbol ) hexinfo | Stores information in a specified j 
| (hexloc/ | virtual storage location. | 


| r i |Examines virtual storage loca— | 
1 X /symbol) | n | |tions. I 
I \ hexloc j |4| | I 

| L J | | 



Figure 16. Summary of DEBUG Subcommands 
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DISK 



Use the DISK command to: 

• Punch disk files to the virtual spooled card punch in a special 
format which allows the punched deck to be restored to disk in the 
form of the original disk file. 

• Restore punched decks created by the DISK DUMP command to a disk 
file. 

The format of the DISK command is: 



DISK | (DUMP 
| ilOAD 



fn ft [fm] 



where : 

DUMP fn ft fm indicates that the specified file (fn ft fm) is to be 
punched. The file may have either fixed or 
variable-length records. After all data is punched, an 
end-of-file card is created with an N in column 5. This 
card contains directory information, and must remain in 
the deck. The original disk file is retained. 



LOAD 



indicates that one or more card files are to be read from 
the spooled card reader and written as CMS files on disk. 
The DISK LOAD operation reads a card deck consisting of 
any number of logical decks previously punched by DISK 
DUMP. The file designations are obtained from the card 
stream. If a file exists with the same designation as one 
of those in the card stream, it is erased and replaced. 
DISK LOAD loads files onto the primary read/write disk. 



Examples 



DISK DUMP MYFILE OLD A1 



The specified file, MYFILE OLD A1, is written to the 
punch and followed by an end-of-file card. 



virtual spooled 



DISK LOAD 

All files which were previously read into the virtual card reader are to 
be loaded onto disk; each file must be followed by an end-of-file card 
as created by the DISK DUMP function. 



Responses 



There is no response to the DISK DUMP command. The file identifiers of 
each file loaded is the response for the DISK LOAD command: 

fn ft fm 
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Other Messages and Return Codes 



DMSDSK002E FILE • f n ft fm' NOT FOUND RC=28 

DMSDSK009E COLUMN 'col' EXCEEDS RECORD LENGTH RC=24 

DMSDSK014E INVALID FUNCTION 'function' RC=21 

DMSDSK037E DISK 'mode' IS READ/ONLY RC=36 

DMSDSK047E NO FUNCTION SPECIFIED RC=24 

DMSDSK048E INVALID MODE 'mode' RC=24 

DMSDSK054E INCOMPLETE FILEID SPECIFIED RC=2U 

DMSDSK062E INVALID * IN FILEID [ 'fn ft f m • ] RC=20 

DMSDSK070E INVALID PARAMETER 'param' RC=24 

DMSDSK077E END CARD MISSING FROM INPUT DECK RC=32 

DMSDSK078E INVALID CARD IN INPUT DECK RC=32 

DMSDSK104S ERROR «nn' READING FILE 'fn ft f m ' FROM DISK RC=100 

DMSDSK105S ERROR 'nn' WRITING FILE ' f n ft f m • ON DISK RC=100 

DMSDSK118S ERROR PUNCHING FILE RC=100 

DMSDSK12US ERROR BEADING CARD FILE RC=100 

DMSDSK205W READER EMPTY OR NOT READY RC=8 
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Use the CHS Editor to: 

• Create, from the terminal, sequential files consisting of either 
fixed or variable length records. 

• Provide, on the basis of certain known filetypes, automatic selection 
of record length, record format, logical tab settings, serialization, 
linemode, and lowercase to uppercase translation. 

• Add, delete, or change any part of a CMS file. 

• Extract all or part of a CMS file to create a new file, or to embed 
it in another file. 

• Allow searching and changing of portions of the file through 
context-directed searches or by using a specific line number. 

• Receive automatic prompting with line numbers. 

• Allow any or all of the file to be displayed at your terminal. 

• Provide an interface to the CMS EXEC interpreter to provide a macro 
facility. Refer to the VM^370: EDIT Guide for a complete description 
of the macro facility. 



The format of the EDIT command is: 



Edit | fn ft [fm] [ (options. ..[) ]] 

options: 
[LRECL nn] 
[MODISP ] 



w her e : 
fn ft 



is the filename and filetype of the file to be created or 
edited. If a file with the specified filename and filetype 
does not exist, the CMS Editor assumes that you want a new 
file created, and after the input environment is entered, 
information entered by you becomes input to that file. If a 
file with the same filename and filetype does exist, the 
EDIT environment is entered, enabling you to issue EDIT 
subcommands and to modify the specified file. Both the 
filename and filetype must be specified. 



fm 



is the filemode of the file to be 
filemode is specified, EDIT sea 
disk. If the filemode is specif 
searches all disks for the existe 
filemode is not specified, only 
extensions are searched. If the f 
saved, and EDIT later writes the 
same disk. If an existing file 
created file is placed on the disk 
or on the primary disk. 



created or edited. If the 
rches only the indicated 
ied as an asterisk, EDIT 
nee of that file. If the 
the primary disk and its 
ile is found, its mode is 
altered file back to that 
is not found, the newly 
specified by the filemode 
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EDIT 



LBECL nn 



HODISP 



is the record length of the file to be created or 
edited. If the record length is not specified, the 
following default values are assumed: 

Editinq Existing Files 

Existing record length is kept regardless of format. 

Creating New Files 

Variable format: « 

Filetype LISTING 121 maximum 

Filetype SCRIPT: 132 maximum 

Filetype FREEFORT: 81 maximum 



Fixed format: 

All filetypes: 



80 



The maximum record length supported by the Editor is 160 
characters. 

forces a display terminal into LINE (typewriter) mode. 
When the NODISP option is in effect, all subcommands that 
are solely for control of display terminals (BACKWARD, 
CHANGE with no operands, FORWARD, and SCROLL (UP) ) are 
made invalid for the EDIT session. 

This option is used when an EDIT session is initialized 
from a local 3270 terminal and the typewriter mode is 
desired. The default mode of operation for an EDIT 
session is DISPLAY for a local 3270 and LINE for a remote 
3270. 

The mode of operation for either terminal can be changed 
during the session via the FORMAT subcommand and the 
DISPLAY or LINE operand, unless the NODISP option is in 
effect. 
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EDIT Subcommands 



Refer to the VM/370: EDIT Guide for a functional description of each of 
the EDIT subcommands. The formats are given in Figure 17 for reference 
only. 



1" - 

| Subcommand Format | Function 


I r i | Scans the next n records of 
| ALter {parml} {parm2} I n r -, | |the file, altering the speci- 
| | * | G | | |fied parameter, either once in 
| I J I * I I |each line or for all occur- 
| l l j j jrences in the line. 


| AUTOsave (n ) | Automatically saves the file 
| \OFFj |on disk after the indicated 
| | number of lines have been 
| (processed. 


| r -x IPoints the current line 
| BAckward | \\ | pointer to a line above the 
j | n| | line currently pointed to. 
| «- J | (For display terminals.) 


| Bottom | Hakes the last line of the 
| | file the current line. 


| r n | Indicates whether translation 
j CASE | U | (to uppercase is to be done, or 
| | M | | displays the current status. 

| L J | 


| r r -n |Changes stringl to string2 for 
| Change /string1/string2|/ | n r t I I IS records or to EOF, either 
| | | J | G HI | for the first occurrence in 
| | | * | * HI |each line or for all 
| l l l jjj |occurrences. 



Figure 17. Summary of EDIT Subcommands and Macros (Part 1 of 5) 
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| Subcommand Format 


| Function | 


| CMS 


Enters CMS subset command | 
|mode. | 


I r t 

1 DEIete 1 n 1 

i i 1 i 
i i*i 

i L j 


IDeletes n lines or to the end | 
|of the file (*) . j 


1 r i 
! DOwn | n ! 

1 111 
1 L J 


IPoints to the nth line from | 
|the current line. | 


| DString /string 


[/] 


deletes all lines from the | 
| current line down to the line | 

containing the indicated | 
Istring. | 


j FILE [fn [ft [fm 


]]] 


i Saves the file being edited onj 
disk or changes its identi- | 
Ifiers. Returns to CMS. | 


1 Find [line] 


| Searches the file for the | 
given line. | 


| FMode [fm] 


Resets or displays the | 
jfilemode. | 


| FName [ f n ] 


IResets or displays the | 
filename. | 


| FOSMat (DISPLAY) 
| (LINE J 


Switches the 3270 terminal | 
(between DISPLAY mode and LINE | 
mode. | 


1 r l 
I Forward | 1 | 
I I n | 

I L J 


Points the current line | 
(pointer to a line currently | 
| pointed to. (For display | 

terminals. | 


I r 
| Getfile fn | ft 

I I * 

I L 


r r r t i t i 
1 fm I m | n | | | | 

1 * 111*1111 

L L L J J J J 


Inserts some, or all, of the | 
j given file following the cur- | 
rent line. | 


I r t 

| IMAGE |0N | 
I |OFF | 
| |CAN0N| 
I L J 


Expands text into line images | 
|or displays current settings. | 


| Input [line] 




Inserts 'line' in the file or | 
| enters INPUT mode. | 


I r t 

| LINEmode |Left | 
I | Bight | 
I IOFF | 
I L J 




[Sets or displays current line | 
setting. I 



| Figure 17. Summary of EDIT Subcommands and Macros (Part 2 of 5) 
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| Subcommand Format | Function 


| Locate /string [/] | Scans file froi next line for 
| | first occurrence of 'string'. 


| LONG | Enters LONG error message 

1 1 U1UUC • 


I r -i |Points to the nth line down 
| Next | n j jfrom the current line. 
(11! ! 

| L J | 


| Overlay line | Replaces all or part of the 
| |current line. 


| PREserve | Saves current mode settings. 


| PROMPT [n] |Sets or displays line number 
| | increment. Initial setting is 
1 MO. 


| QUIT (Terminates EDIT session with 
| |no updates since last 'SAVE'. 


| r t | Sets or displays record format 
| RECfm | F | | for subsequent files. 
I I V | | 

| L J | 


| r r in (Recomputes line numbers for 
| RENum |strtno |incrno| | | VSBASIC and FREEFORT source 
1 IIS |strtno| | | files. 

| L L JJ | 


j r -, | Executes the following OVERLAY 
| REPEAT | n | (subcommand n times. 
1111 j 
11*1 1 

| L J | 


| Replace [line] (Replaces the current line with 
| I'line' or deletes the current 
| |line and enters INPUT mode (if 
| |no data line is specified). 


| REStore I Restores mode settings to 
| lvalues last preserved. 


| RETURN IReturns to EDIT environment 
| |from CHS subset. 


| (REUSE) [subcommand] | Stacks (LIFO) the last EDIT 
| \ = / (subcommand that does not start 
| (with REUSE or the question 
j |mark (?) and then executes any 
| | given EDIT subcommand. 



Figure 17. Summary of EDIT Subcommands and Macros (Part 3 of 5) 
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GC20-1804-3 Page Modified by TNL GN20-2659 
EDIT 



| Subcommand Format | Function | 


| SAVE [fn [ft [fm]]] |Saves the file on disk and | 
I | stays in EDIT environment. | 


I r t | Display a number of lines | 

| S[croll][Up] |* | | above or below the current | 

I |n | | line. (For display terminals.) | 

I II I I I 
I i j I I 


| SERial ( OFF r n \ |Turns serialization on or off | 
| J ON |incr | f |in columns 73 through 80. | 
| ) ALL I JO | ? | | 
| ( seq L J ) I I 


| SHORT | Enters SHORT error message | 
| | mode. | 


| r n | Stacks n lines, beginning with| 
| STACK | n | | current line, in terminal | 
| \ 1 \ linput buffer. | 
| | subcommand! | | 

| L J I | 


| TAESet {n1 n2 ... nx } |Sets the given tabs. | 


| TOP | Points to the beginning of thej 
I Ifile. | 


| r n |Sets or displays the column of| 
| TRUNC | n j | truncation. An asterisk (*) | 
| I * I |means end of logical record. | 

| L J 1 | 


I r r i t | Displays m lines beginning | 
| Type | m | n | | | with the current line or the | 
I | 1 | * | | Ibeginning of the file. | 
I I * I ! I I i 

| L L J J 1 | 


I r n | Points to the line 'n' lines | 
I Op | n | | above the current line. | 
I I 1 1 ! 1 

| L J | | 


I r t rr i i |Sets, displays, or resets j 
| Verify | OH j | | started lend col | |verify mode. The asterisk (*) | 
| |OFF| || 1, | * | |means end of logical record. | 

| L J LL J J | | 


I r t | Assigns to X or Y the given | 
| (X) | subcommand | |EDIT subcommand or executes | 
| \Y J | n | | the previously assigned sub— | 
| 1 J 1 Icommand n times. | 

1 L J | 1 


| r r t t |Sets or displays the columns | 
| Zone | m | n | | I between which editing is to | 
I | 1 j | * j I | take place. I 
I I * I I I I I 

| L L J J 1 | 



Figure 17. Summary of EDIT Subcommands and Macros (Part 4 of 5) 
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BDIT 



Subconand Format 



I 



Function 



| Displays the last EDIT subcom- 
mand which did not begin with 
I reuse or a question mark (?) . 



nnnnn [text] 



| Locates the line specified by 
| the given line number and in— 
jserts text if given. 










Up ■ 
Down ■ 
TO label 



Itiies. $DUP is an BDIT macro. 

I 
I 

| doves n lines up or down a 
|lines.~$BO?B is an EDIT Macro. 

I 



| Figure 17. Summary of EDIT Subcommands and Hacros (Part 5 of 5) 

Responses 

HEW FILE: 

The specified file does not exist. 



EDIT: 



The BDIT environment is entered. The logical tab settings aay be 
either those defined by the user or those assumed according to the 
filetype. An BDIT subcommand aay now be issued. 



INPUT: 



The input environment is entered by issuing the BDIT subcoaaands 
REPLACE or INPUT with no operands. All subsequent input lines are 
accepted as input to the file. 



?EDIT: line 



"line" was entered in the BDIT environaent and is an invalid EDIT 
subcommand or macro. This message appears while in LONG error 
message mode. 



An invalid subcommand was entered in 
SHORT error message mode. 



the EDIT environment while in 



-$ 



An invalid 
mode. 



EDIT macro was entered while in SHORT error message 
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Other Me ssa ges and Return Codes 

DMSEDI003E INVALID OPTION 'option* RC=24 

DMSEDI024E FILE *£n ft £■• ALREADY EXISTS RC=28 

DMSEDI029E INVALID PARAMETER *paraa* IN THE OPTION 'LRECL' FIELD RC=24 

DMSEDI044E RECORD LENGTH EXCEEDS ALLOWABLE MAXIMUM RC=88 

DHSEDI054E INCOMPLETE FILEID SPECIFIED RC=24 

DHSEDI076E ACTUAL RECORD LENGTH EXCEEDS THAT SPECIFIED RC=40 

DHSEDI104S ERROR *nn« READING FILE * f n ft fm» FROM DISK RC=100 

DMSEDI105S ERROR *nn* WRITING FILE *fn ft fm« ON DISK RC=100 

DHSEDI132S FILE «fn ft fa* TOO LARGE RC=88 
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ERASE 



Use the ERASE coaaand to delete a file or a related group of files froi 
a read/write disk. The file to be deleted Bust not be on a read-only 
disk. The format of the ERASE coaaand is: 



| ERASE | 
I I 



fn 



ft 



[fa] [ (options.. .[) ]] options; 

r t 
| Type | 
IFptJBel 



where; 
fn 



is the filenaae of the files to be erased. An asterisk Bay be 
coded in this position to indicate that all filenames are to be 
used. This field Bust be specified, either with a name or an 
asterisk. 



ft is the filetype of the files to be erased. An asterisk aay be 
coded in this position to indicate that all filetypes are to be 
used. This field Bust be specified, either with a naae or an 
asterisk. 

fa is the fileaode of the files to be erased. If this field is 
omitted, the primary read/write disk is searched for the files 
to be erased. 

Note: If asterisk is specified for filenaae and filetype then fileaode 
aust be specified. The fileaode Bust include both a aode letter and 
number. 



Options 



TYPE displays at the terainal the file identifier for each file 
erased. 

HOTYPB file identifiers are not displayed at the terainal. 



ERASE OLDFILE TEMP (TYPE) 

The file with the identifier OLDFILE TEHP, if located on the priiary 
read/write disk, is erased. Its file identifier is displayed at the 
terainal. 



fn 



ft 



fa 



If the TYPE option is specified, the file identifier for each file 
erased is displayed. 
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ERASE 

Other Messages and Return Codes 

DMSERS002E FILE [ • f n [ft [fa]] 1 ] MOT FOUND RC=28 

DMSERS003E IHVALID OPTION •option 1 RC=24 

DMSERS037E DISK »aode» IS READ/ONLY RC=24 

DMSERS048E IHVALID MODE *node* RC=24 

DMSERS05UE INCOMPLETE FILEID SPECIFIED RC=2U 

DMSERS069E DISK •aode(cuu) 1 NOT ACCESSED RC=36 

DMSERS070E INVALID PARAMETER 'paran* RC=2*» 

DMSERS071E ERASE * * [*] NOT ALLOWED RC=2U 

I Note: You can invoke the ERASE coaaand froa the terainal, froa an EXEC 

| file, or as a function froa a prograa. If ERASE is invoked as a function 

| or froa an EXEC file that has the &CONTROL N0MS6 option in effect, the 

| DMSERS002E FILE fn ft fa NOT FOUND error aessage is not issued. 
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EXEC 



Use the EXEC command if you want to be able to execute one or more CHS 
commands or EXEC control statements contained in a specified file by 
issuing a single command. If this command is entered from the CHS 
command mode but not nested within another EXEC procedure, the initial 
word 'EXEC* may be omitted. The format of the EXEC command is: 



| EXec | fn [args...] 



where: 
fn 



is the filename of a file containing one or more CHS commands to 
be executed. The filetype of the file must be EXEC and the file 
must be fixed format with a logical record length not exceeding 
130 characters. EXEC files can be created with the EDIT command 
or by a user program. EXEC files created by the CHS Editor have 
a logical record length of 80 characters. Each EXEC file can 
contain a maximum of 4096 lines. 



args are the arguments to replace the numeric variables in the EXEC 
file specified. Within an EXEC file, up to thirty symbolic 
variables can be used (each one indicated by an ampersand (S) 
followed by an integer ranging from one to thirty) to indicate 
values which are to be replaced when the EXEC file is executed. 
The arguments are assigned to symbolic variables in the order in 
which they appear in the argument list. For example, each time 
an 61 appears in an EXEC line, the first argument specified with 
the EXEC command temporarily replaces the £1, the second 
argument specified with the EXEC command replaces &2, and so on, 
to argument H of the EXEC command. 

If the percent sign (%) is used in place of an argument, the 
corresponding variable (&N) is ignored in all the commands which 
refer to that variable. If the specified EXEC file contains 
more variables than arguments given with the EXEC command, the 
higher numbered variables are assumed to be missing, and are 
ignored when the commands are executed. 



EXEC CONTROL ST1TEHEHTS 



Control statements begin with a control word, which is usually followed 
by a list of tokens, and in some cases by additional lines of data. 
Figures 18 and 19 list the control statements and their functions and 
the EXEC built-in functions. Refer to the VH^370: EXEC User's guide for 
detailed information on how to use EXEC. 



Section 7: Format and Usage Rules for CHS Commands 127 



EXEC 



r— '■■'■- ' ■■ " ■ - i 

| Control Statement | Function | 


1 Svariabie = ae (Assigns the value of ae to | 
| |the symbol specified by | 
| l&variable; ae is an algebraic | 
| (expression; the equal sign | 
1 | must be preceded and followed | 
| |by a blank. I 


| &ARGS [arg! [arg2 ••<]] |Redefines the arguments &1, j 
| | 82 , ... with the value of | 
I I'argl', 'arg2', ..., and re— | 
| | sets the variable &INDEX. | 


| SBEGPONCH [ALL] I Punches • linel ', »line2', ... | 
| linel |into the card punch, without | 
| line2 |tokeni2ing them. | 

1 • I t 

| &END | I 


1 r t r t |Stacks 'linel', 'line2', . .., | 
| SBEGSTACK 1 FIFO I |ALL| | in the console input buffer | 
j |LIFO| L J | without tokenizing them. | 
| linel •- j | I 
| line2 I I 

1 • 1 1 

| SEMD | | 


( &BEGTYPE [ALL] (Displays 'linel', 'line2', ...| 
| linel j at the console, without token-j 
| line2 |izing them. I 

1 • 1 1 

| &END | | 


j &CONTINUE (Provides a branch address for j 
I l&EBBOR, SGOTO, and other con- j 
| (ditional branching statements.! 


j &CONTROL |Sets, until further notice, ( 
(r ir i r i r n |the characteristics of the | 
| |OFF ( (TIME | |PACK | (MSG | (summary of execution, which isj 
| |EBROR| |NOTIHE| | UNPACK | |HOHSG| (automatically printed at the | 
| |CMS | »• J l J •- J |console. I 
1 |ALL | | I 

| L J | | 


| &EBBOB action I Executes 'action' following | 
1 |any CHS command which yields | 
| |an error return code (that is, | 
I (a return code which is not j 
| | zero) . 'action' can be any | 
| (executable statement. j 



Figure 18. Summary of EXEC Control Statements (Part 1 of 3) 
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EXEC 



Control Statement 



Function 



r i 

SEXIT | returncode) 

i ( 

L J 



Exits from the EXEC file with 
the given return code. 



SGOTO (TOP 

< linenumber 
(label 



Transfers control to the top 
of the EXEC file, to the given 
line, or to the line starting 



■ - ■*- *- ■ "• - V. . 



£If 



tokenl 

&$ 

S* 



EQ j (token2 

I LTV (s* 
|LE( 

GT | 

GE / 



executable 
statement 



Executes the 'executable 
statement 1 if the condition is 
satisfied. 



SLOOP 



(label J (condition/ 



Loops through the following n 
lines, or down to (and includ- 
ing) the line starting with 
•label 1 , for m times, or until 
•condition 1 is satisfied. 



&PUNCH tokenl [token2 ... ] 



Punches a card containing 
tokenl, token2, ... 



SREAD |n 

|ARGS 

|VARS varl [var2 . 

L 



] I 

J 



Reads the next n lines from 
the terminal and treats them 
as if they had been in the 
EXEC file; or reads a line, 
assigns the tokens in it to 
the arguments &1, 62, ..., and 
resets SINDEX to the number of 
arguments thus set; or reads a 
single line and assigns the 
tokens in it to the variables 
«var1», »var2», ... 



&SKIP 



r i 

I n | 

I J I 

L J 



If n > 0, skips the next n 
lines of the EXEC file. If 
n < 0, transfers control to 
the line which is n lines 
above the current line. If 
n * o, transfers control to 
the next line. 



r t 

&SPACE | n | 

I J I 
i j 



Displays n blank lines at the 
terminal. 



r t 
8STACK |FIF0| [tokenl [token2 
|LIF0| 

L J 



]] 



Stacks a line in the terminal 
input buffer containing 
•tokenl •, •token2*, ..., or 
stacks a null line if the 
tokens are absent. 



Figure 18. Summary of EXEC Control Statements (Part 2 of 3) 
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EXEC 



Control Statement 



Function 



1 - 

| r -| | Displays tiling information. 
| &TIHE |0N | | 
1 IOFF | | 
| |RESET| | 
| |TTPE | | 

| L J | 


1 &TTPE tokenl [token2...] |Prints at the terminal a line 
| (containing 'tokenl, 1 'token2, 1 

1 1 • • • 



Figure 18. Summary of EXEC Control Statements (Part 3 of 3) 



EXEC Built-in Functions 



An EXEC built-in function consists of the name of the function and, 
usually, a list of arguments. Built-in function names are EXEC 
keywords, and start with an ampersand. with the exception of &LITERAL, 
they are recognized only if they appear as the token following the equal 
sign of an assignment statement. Figure 19 lists the EXEC built-in 
functions with their format and an explanation. 



r — 

| Built- 


-in Function 


| Explanation | 


i &CONCAT tokenl [ 


token2 . .. ] 


(Concatenates •tokenl 1 , J 
|*token2', ..., into a single | 
|token, with a maximum length | 
|of eight. | 


| 6DATATYPE token 




| Bas the value HUH or CBAB, | 
(depending on the data. | 


1 SLength token 




IGives the number of nonblank ( 
(characters in •token 1 . | 
1 1 


1 SLIteral token 




|Uses the literal value of | 
(•token 1 , without substitution | 
(for any EXEC variable which | 
| may appear in it. | 


| &SDBSTR token i 


[J] 


(Extracts that part of 'token 1 ( 
| which starts at character M i w , I 
|with length "j"; or which | 
| starts at character w i w and | 
|runs to the end of the token, j 



Figure 19. Summary of EXEC Built-in Functions 



Responses 



As each CMS command in the EXEC file is processed, it is displayed at 
the terminal along with any nonzero return code. The &COHTROL command 
can be used to augment or reduce the amount of displaying done during 
execution. 
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If the EXEC interpreter finds an error, it displays the message: 

ERROR IN FILE « f n EXEC f m« , LINE n, ^description of error 1 

where "description of error" is one of the following conditions with its 
appropriate return code: 

Return 

Code Description 

(802) 6SKIP OR &60T0 ERROR 

(804) TOO MANY ARGUMENTS 

(805) MAX DEPTH OF LOOP NESTING EXCEEDED 

(806) DISK OR TERMINAL READ ERROR 

(807) INVALID SYNTAX 

(808) INVALID FORM OF CONDITION 

(809) INVALID ASSIGNMENT 

(810) MISUSE OF SPECIAL VARIABLE 

(811) ERROR IN &ERROR ACTION 

(812) CONVERSION ERROR 

(813) TOO MANY TOKENS IN STATEMENT 

(814) MISUSE OF BUILT-IN FUNCTION 

(815) EOF FOUND IN LOOP 

(816) INVALID CONTROL WORD 



Error Messages and Return Codes 



DHSEXC001E NO FILENAME SPECIFIED RC-24 
DMSEXC002E FILE »fn ft» NOT FOUND RC=28 
DMSEXC034E FILE • f n ft fm« IS NOT FIXED LENGTH RC=32 
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FILEDEF 



Use the FILEDEF command to define an OS ddname and to relate that ddname 
to a device on your virtual ■achine. If the device is a disk, FILEDEF 
assigns a CHS file identification (that is, fn ft fm) and, if the disk 
is an OS disk, an OS data set naie; or, if the disk is a DOS disk, a DOS 
file-id. Also, using FILEDEF, you can specify OS DCB parameters that 
describe the ddname just as they would on the OS Job Control Language 
Data Definition statement. In general, FILEDEF is used to define ddnames 
for programs written using the language processors supported by VH/370. 
You can find usage information on FILEDEF in "Usincr OS Programs and 
Macros Under CHS" in Section 4. 

The format of the FILEDEF command is: 



Flledef 




option A: 

r t 

ISECASE | 
|LOWCASE| 

L J 



Terminal 

PRinter 

PUnch 

Reader 



[ (optionA optionD[) ]] 
[ (optionD[) ]] 



r r n 

DISK |fn ft If m|| [ (optionB optionD[) ] ] 

I FILE ddname |A1 | | 

L "~ L JJ 



rr i r m 

| | DISK fn ft ||fm| | fDSH ? 

II FILE ddname I |A1 II (DSH guall qual2 . 

LL J t JJ 

[ (optionB optionD[) ]] 



• •} 



DUMMY 

TAPn 

CLEAR 



[(optionD[) ]] 

[ (optionC optionD[) ]] 



opt io nB; 
[KEYLEH nn] 

r t 

IXTEHT nn| 
I XT E NT 50 1 

L J 

[LIMCT nn] 

[OPTCD a] 

[DISP MOD] 

[MEMBER membername ] 

[COHCAT] 

r t 

IDSORG (PS 

I )po 

I )DA 

I (is 



opt i one : 

r i 

|7TRACK| 
|9TRACK| 

L J 

[TRTCH a] 
[DEN den] 



o ptionD ; 
[PERM] 

r i 

I CHANGE | 
|NOCHAHGE| 
c J 

[RECFH a] 
[LRECL nn] 

r 

I BLOCK nn 
IBLKSIZE nn 



I 
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where: 

ddname 
nn 



is the naie by which the file is referred to in your 
program. If a number nn is specified, it is translated to a 
FORTRAN* data definition name of FTnnFOOL If the CLEAR 
operand is specified, ddname may be specified as an asterisk 
(*) to indicate that all file definitions not entered with the 
PERU option are to be removed. 



Devices 

TERMINAL is your terminal (terminal I/O should not be blocked) . 
PRINTER is the spooled printer. 



PUNCH 



is the spooled punch. 



READER is the spooled card reader (card reader I/O should not be 
blocked) . 

DISK specifies that the virtual I/O device is a disk. As shown in 
the format, you can choose one of two forms for specifying the 
DISK operand. Both forms are described in the section that 
follows, "Using the FILEDEF DISK Operand." 

DUMMY indicates that no real I/O is to take place for a disk data 
set. 

TAPn is a magnetic tape. The symbolic number of the tape drive, nn, 
can be 1, 2, 3, or 4, representing virtual units 181, 182, 
183, and 184 respectively. 



CLEAR 



removes any existing definition for the specified ddname. 



Pi aa T*"i t»< 



a i^/lnama 



A A'F ■! « n t* ; 



cuiauA. Co 



definition does not exist and that any options previously 
defined with the ddname no longer have effect. 

If no operands are entered with the command, a list of current filet ypes 

is displayed at the terminal including the ddname, device type, and, if 

device type is DISK, the filename, filetype, and filemode. Also, if the 

| FILEDEF is for an OS data set, the data set name is displayed; or, if 

| the FILEDEF is for a DOS file, the file-id is displayed. 



Whenever an option is specified that is invalid for a particular 
device type, an error message is issued. Figure 20 shows valid 
options for each device type. 



1 The FORTRAN processors are Program Products. 
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Unit 


Record 








Option 


BEADEB, PDHCH 






DISK 




PBINTEB 


TEBHINAL 


I TAPn 


DDMHY* 


BLOCK, BLKSIZE 




X 


X 


1 x 


X 


CHANGE, NOCHANGE 




X 


X 


X 


X 


COHCAT 










X 


DEN 








X 




DISP HOD 










X 


KEYLEN 










X 


LIHCT 










X« 


LOWCASE, DPCASE 






X 






LBECL 




X 


X 


i x 


X 


HEHBEB 










X 


OPTCD 










X2 


PEBH 




X 


X 


X 


X 


RECFH 




X 


X 


x 


X 


TRTCH 








X3 




XTEHT 










X 


7TRACK, 9TRACK 








X 





*No options may be necessary but all disk options are accepted. 
2 This option is used for BDAH files. 
3 This option is for 7— track tapes only. 

i i 

Figure 20. Valid File Characteristics for Each Device Type for the 
FILEDEF Command 

DPCASE translates all terminal input data to uppercase. 
LOWCASE retains all terminal input data as typed in. 

KEYLEH nn is the size (nn) of the key (in bytes) . 

XTENT nn is the number of records (nn) in the extent for the file. 
The default is 50. 

LIHCT nn is the maximum number of extra tracks or blocks (nn) to 
be searched. This option is used for BDAH files. 

OPTCD a is the direct access search processing desired. The 
variable a may be any combination of up to three of the 
following: (A and B are mutually exclusive.) 

Code DASD Search 

A Actual device addressing 

E Extended search 

F Feedback addressing 

R Belative block addressing 

DISP HOD positions the read/write pointer after the last record in 
the disk file. 

HEHBEB membername 

allows you to specify the name of a member of an OS 
Partitioned Data Set; membername is the name of the PDS 
member. 
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CONCAT allows you to concatenate OS data sets with each other 
and with CHS files. You must use the CONCAT option vhen 
you are defining an OS data set referred to by a later 
GLOBAL command (COHCAT is not necessary for CHS files 
referred to in a later GLOBAL command.) 

CONCAT should be used only for macro libraries to be 

specified in a later GLOBAL command. You must specify 

CONCAT vith all of the OS data sets you define, including 
the first. 



DSOBG 




Mhen you use CONCAT in a FILEDEF command, you can specify 
more than one FILEDEF for a particular ddname. 

Also, when you use CONCAT, the DCB parameters used are 
those associated with the first filename you specify in a 
GLOBAL command for a macro library. 

is the data set organization: physical seguential (PS) , 
partitioned (PO) , direct access (DA) , or indexed 
seguential (IS) • 



r i 
| 7TRACK | 
| 9TRACK | 



is the tape setting. 



TBTCH a is the tape recording technigue. 
to determine the value of a: 



Use the following chart 



r 

1 a 
i 


Parity 


| Converter 


| Translator j 


i 
1 o 


odd 


| off 


1 off | 


I oc 


odd 


on 


off | 


| OT 


odd 


| off 


on | 


1 E 


even 


off | 


off | 


| ET 

i 


even 


off 


on | 



DEN den is tape density: den can be 200, 556, 800, 1600, or 6250 
bpi (bits per inch) . If 200 or 556 are specified, 7TBACK 
is assumed. If 800, 1600, or 6250 are specified 9TRACK is 
assumed. 



PERH 



retains the current definition until it either is 
explicitly cleared or is changed with a new FILEDEF 
command with the CHANGE option. If PERH is not 
specified, the definition is cleared when a FILEDEF * 
CLEAR command is executed. 



CHANGE merges the file definitions whenever a file definition 
exists for a ddname and a FILEDEF specifying the same 
ddname is issued: the options associated with the two 
definitions are merged. Options from the original 
definition remain in effect unless duplicated in the new 
definition. New options are added to the option list. 



NOCHANGE retains the current file definition, if one 
the specified ddname. 



exists, for 
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BECFM a is the record format of the file, where a can be one of 
the following: 

a Meaning 

F fixed length 

FB fixed blocked * 

V variable length 

VB variable blocked 1 

undefined 

FS,FBS fixed length, standard blocks 

VS,VBS variable length, spanned records 

A ASA print control characters 2 

H Machine print control codes 2 

LBECL nn is the logical record length (nn) of the file, in bytes. 
LBECL should not exceed 32,767 bytes because of OS 
restrictions. 

BLOCK nn is the logical block size (nn) of the file, in bytes. 
BLKSIZE nn BLOCK should not exceed 32,767 bytes because of OS 
restrictions. 

If a CHS file is fixed and has 80-byte CHS records, you 
should specify BBCFH FB BLOCK 800 LBBCL 80 and a filemode 
number of 1. (BLOCK can also be expressed as 80*10.) 
There can be significant performance improvenent for CHS 
fixed files if the block size is a multiple of 800. 

Motes; 

~1. There is an auxiliary processing option for FILEDEF that is only 
valid when FILEDEF is executed by an internal program call: this 
option cannot be entered on a terminal command. The option, 
AOXPROC addr, allows an auxiliary processing routine to receive 
control during I/O operations. 

2. DOS files do not contain BLKSIZE, LRECL, or BECFH specifications. 
These options must be specified by a FILEDEF command or DCB 
statement. Otherwise the defaults, BLKSIZE=32760 and RECFH=0, are 
assumed. LBECL is not used for BECFH-D files. 

3. If V or YS is specified for BECFH, LBECL must be at least 4 bytes 
less than BLKSIZE. BLKSIZE must be specified if LRECL is 
specified. The FILEDEF command does not provide default values for 
LBECL and BLOCKSIZE. However, the following chart describes the 
results of specifying BLOCKSIZE and LBECL. 



'FB and VB should not be used with TERMINAL or READER devices. 
2 A and H may be used in conjunction with any of the valid RECFH settings 
(for example, FA, FBA, VA, VBA, etc.) 
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BLKSIZE | LRECL | Results 



not | not |If the input file exists on disk, the item 
specified | specified |length becomes the BLKSIZE (or BLKSIZE + 4 
| | for variable length records). 



specified | not jLBECL^BLKSIZE (or LRECL=BLKSIZE-4 , for 
| specified | variable-length records). 



not | specified | BLKSIZE=LRECL (or BLKSIZE=LRECL+4, for 
specified | (variable-length record) . 



specified | specified {The values specified are used. 



L 



Using the FILEDEF DISK Operand 

There are two general forms for specifying the FILEDEF DISK operand. If 
you specify the first form: 

DISK fn ft [fm] 

fn and ft (filename and filetype) are assumed to be a CHS fileid. If 
the filemode is for an OS disk, fn and ft are assumed to be the only two 
gualifiers of an OS data set name. In this form, the filemode you 
specify must always match the access mode of the disk on which the data 
set resides. The default values for fn ft fm are FILE ddname A1. 

You cannot use this form unless the OS data set. name or DOS file-id 
conforms to the OS naming convention (one- to eight-byte gualifiers 
separated by periods, to a maximum of 44 chracters, including periods) . 
Also, the data set name can have only two gualifiers; otherwise, you 
must use the DSN ? or DSH quail... form. For example, if the data set 
name or file-id is TEST. SAMPLE. MAY, you enter: 

| FILEDEF MINE B1 DSN TEST SAMPLE MAY 

— or -- 

| FILEDEF MINE B1 DSN ? 
TEST. SAMPLE. MAY 

If the data set name or file-id is TEST. SAMPLE, then you enter: 

| FILEDEF MINE DISK TEST SAMPLE B1 

The second form of the DISK operand is only for use with OS data sets 
and DOS files: 



| FILEDEF ddname |DISK fn 
I I 

| L J L J 



fn ft I | fm | J DSN ? ) 

Hi! Mfiaael | AH \ DSN quail [qual2...]/ 



This form allows you to specify a DSN operand that corresponds to the 
DSN parameter on the DD card describing an OS data set or DOS file. 
There are three ways you can specify this form: 
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| 1. FILEDEF ddname DISK fn ft fm DSH quail [gual2...] 

If you use this fori, the FILEDEF command associates the filename 
and filetype you specify with the OS data set name or DOS file-id 
specified following the DSN operand. Once it is defined, you can 
refer to the OS data set name or DOS file-id by coding the filename 
and filetype. If you omit DISK, filename, filetype, and filemode, 
the default values are FILE ddname A1. 

| 2. FILEDEF ddname DSN ? 

This form of the FILEDEF command allows you to specify the DSN OS 
data set name or DOS file-id interactively. Using this form, you 
can enter an OS data set name or DOS file-id containing embedded 
special characters such as blanks and hyphens. If you use this 
form, the default filename and filetype for your file, FILE ddname, 
is the filename and filetype associated with the OS data set name 
or DOS file-id. The filemode for this form is always the default, 
A1. 

The interactive DSN operand works this way: when you enter DSN ?, 
CMS requests that you enter the OS data set name or DOS file-id 
exactly as it appears in the data set or file. Do not omit the 
periods that separate the qualifiers of an OS data set name, but do 
not insert periods where they do not appear. 

qual1[ .qual2. . . ] 

where quail .qual2. . . are the qualifiers of the OS data set name or 
DOS file-id. When you use this form, you must code the periods 
separating the qualifiers. 

| 3. FILEDEF ddname B1 DSN quail [qual2...] 

This form allows you to specify the OS data set name or DOS file-id 
explicitly. (This form can be used for DOS file-ids only if they 
comply with the OS naming convention of one- to eight-byte 
qualifiers separated by periods, to a maximum of 44 characters, 
including periods.) Again, the default value for the filename is 
FILE and for filetype, the default value is the name associated 
with the OS data set name or DOS file-id. The filemode for this 
form is B1 as you specified it on the command. When you use this 
form, you must omit the periods that separate the qualifiers of the 
OS data set name. For example, for an OS data set or DOS file 
named MY. FILE. IH, you enter 

| FILEDEF ddname B1 DSN MY FILE IN 

All of these forms have many variations, as is apparent from the 
command format. 

Note: When the FILEDEF command is used to define a ddname, that 

definition remains in effect until another FILEDEF command (with the 

CLEAR option) is issued or until the system clears the definition. The 
system clears FILEDEF definitions if: 

• Any of the CMS language processors are executed. The language 
processors always issue, at their completion, the command FILEDEF * 
CLEAR. This command causes all FILEDEF definitions to be cleared, 
except for those defined with the PERM option. 
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If you want any FILEDEF definitions to remain in effect after a 
language processor has executed, define them with the PERM option. 

An ABEND occurs. When you enter your next command, ABEND recovery 
takes place. ABEND recovery clears all previously specified FILEDEF 
definitions, including those for which the PERM option was 
specified. All the FILEDEF definitions must be respecified after 



Examples 

FILEDEF MACLIE DISK SYS1 MACLIB B1 (MEMBER ABEND) 

When the CMS file SYS1 MACLIB or, if the B disk is an OS disk, the OS 
data set SYS1. MACLIB is opened, the read/write pointer is set to the 
start of the partitioned data set member ABEND. 

FILEDEF ASSEMBLE DISK TEST ASSEMBLE B1 DSN SAMPLE OS DATA 

When an OS macro or a CMS command references the fileid TEST ASSEMBLE 
B1, it gets information from the OS data set SAMPLE. OS. DATA. For 
example, the command ASSEMBLE TEST assembles the OS data set 
SAMPLE. OS. DATA. 

FILEDEF SYSPRINT PRINTER (PERM RECFM F BLOCK 132) 

Whenever SYSPRINT is referred to in your program, the output written 

is spooled to the virtual printer. The file is fixed-format with a 

logical block length of 132. The file definition is not removed by the 
command FILEDEF * CLEAR. 

FILEDEF PRINTOUT TERMINAL (UPCASE NOCHANGE 

If a file definition for the ddname PRINTOUT does not exist, one is 
established. Output written to PRINTOUT is displayed at the terminal in 
uppercase. 

FILEDEF DISK DISK NAME OLDFILE 

All I/O for a file with a ddname of DISK is directed to a disk file 
with a file identifier of NAME OLDFILE. 

FILEDEF DISKFILE DUMMY 

When any I/O command is issued to a disk file with a ddname of 
DISKFILE, the real I/O operation is not performed. 

FILEDEF HEWMAST TAP2 (9TRACK DEN 1600 RECFM FB LRECL 050 BLOCK 3000 

I/O commands issued to a file with ddname of NEWMAST are directed to 
the tape located at logical unit TAP2. The tape is 9-track, and 
recording is done at 1600 bpi. The tape is in fixed-block format with a 
logical record length of 50 and a physical blocksize of 3000. 
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FILEDEF CMSLIB DISK CS 1 MACLIB * DSN OS DATA 1 (LRECL 80 BLOCK 800 RECFM FB CONCAT) 
FILEDEF CMSLIB DISK OS2 MACLIB * DSN OS DATA 2 (CONCAT) 
FILEDEF CMSLIE DISK SYS1 MACLIB * (CONCAT) 
GLOBAL MACLIB OS1 OS2 SYS1 HYLIB 



This example shows how you can use the CONCAT option to cause CMS to 
search the OS naclibs OS. DATA. 1, OS. DATA. 2 and SYS1. MACLIB and the CMS 
maclib MYLIB to resolve maclib references in assembling the CMS file 
SAMPLE ASSEMBLE. 

ACCESS 193 B 

ACCESS 194 C 

FILEDEF CMSLIB DISK ASP1 MACLIB * DSN ASP1 MACROS RL1 (RECFM FIXED BLOCK 3360 LRECL 80 CONCAT) 

FILEDEF CMSLIB DISK ASP2 MACLIB * DSN ASP2 MACROS RL2 (CONCAT) 

FILEDEF CMSLIB DISK SYS1 MACLIB * (CONCAT) 

FILEDEF ASSEMBLE TEST SAMPLE B1 DSN TEST OS SAMPLE1 

GLOBAL MACLIB ASP1 ASP2 SYS1 CMSLIB 

ASSEMBLE TEST 

This example shows how you can use FILEDEF to override the default 
FILEDEF commands CMS gives you for an assembly. The example also shows 
how to point to an OS disk containing OS source for TEST.OS.SAMPLE1 and 
the OS macro libraries ASP. MACROS. RL1 , ASP. MACROS. RL2 r and SYS1. MACLIB. 
The GLOBAL command accesses four macro libraries and the order of search 
for the macros needed during assembly, that is, ASP1 first, ASP2 next, 
and so on. The first three libraries are OS libraries and CMSLIB is a 
CMS macro library. 

| Note; A disk does not have to be accessed at the time a FILEDEF is 
| issued; however, if this is the case, a warning message is issued to the 
| user informing him that the disk is not accessed. 



Responses 



ddnamel devicel [filenamel filetypel] 



ddnameN deviceN [filenameN filetypeN] 



A list of current definitions is displayed if the FILEDEF command 
is entered with no operands. 

DMSFLD220R ENTER DATA SET NAME: 

A FILEDEF command with the DSN ? operand was entered. Enter an OS 
data set name the form guall .gual2. . . .gualn ; where guall, qual2 
through qualn are the qualifiers of an OS data set name. 

DMSFLD704I INVALID CLEAR REQUEST 

A CLEAE request was entered for a file definition that does not 
exist; no action is taken. 
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Other Messages and Return Codes 

DMSFLD003E INVALID OPTION 'option 1 RC=24 

DMSFLD023E NO FILETYPE SPECIFIED RC=24 

DMSFLD027E IHVALID DEVICE 'device name* RC=24 

DMSFLD029E INVALID PARAMETER 'param' IN THE OPTION 'option 1 FIELD RC=24 

DMSFLD035E INVALID TAPE MODE RC=24 

DMSFLD050E PARAMETER MISSING AFTER DDNAME RC-24 

DMSFLD065E 'option' OPTION SPECIFIED TWICE RC=24 

DMSFLD066E 'option' AND 'option' ARE CONFLICTING OPTIONS RC=24 

DMSFLD070E INVALID PARAMETER 'param* RC=24 

DHSFLD221E INVALID DATA SET NAME 'data set name' RC=24 

DMSFLD224E FILEID ALREADY IN USE RC=2U 
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Use the FORMAT command to: 

• Initialize a virtual disk area in the CMS format. 

• Count the number of cylinders on a virtual disk. 

• Mrite a label on a virtual disk. 

• Reset the number of cylinders on the virtual disk. 

| This command can be used with a virtual 3340, 3330, 2314, or 2319 
direct access storage device. The format of the FORMAT command is: 



FORMAT | cuu mode [nocyl] [ (options. ..[) ]] 

options: 

r t 

| LABEL | 
| RECOUP | 

L J 



where: 
cuu 

mode 
nocyl 



is the virtual 
formatted. 



device address of the virtual disk to be 



Note that 000 is not a valid address. 

is the filemode letter to be assigned to the specified device 
address. Valid filemode letters are A, 8, C, D, E, F, G, T, and 
Z. This field must be specified. 

is the number of cylinders to be made available for use. All 
available cylinders on the disk are used if the number specified 
exceeds the actual number available. 



Options 

LABEL writes a label on the disk without formatting the disk. A 
six-character label is written on cylinder 0, track 0, record 
3 of the virtual disk. A prompting message requests a 
six-character disk label (less than six is left-justified, 
blank padded). 

RECOHP changes the number of cylinders on the disk which are 
available to the user to the actual number of minidisk 
cylinders or to the number specified by nocyl, whichever is 
less. If nocyl is not specified, all cylinders are used. 



Mote: If neither RECOMP nor LABEL is specified, the disk area is 
initialized by writing a device— dependent number of records (containing 
binary zeros) on each track. Any previous data on the disk is erased. 
A read after write check is made as the disk is formatted. 
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Exanples : 

FORMAT 191 A 25 

Initializes 25 cylinders of the disk located at virtual address 191 in 
CMS format. 

FORMAT 192 B 25 (RECOMP) 

Changes the number of cylinders available at virtual address 192 to 25 
cylinders. 

FORMAT 193 C (LABEL) 

Writes a label on the disk at virtual address 193. Respond to the 
prompting message with a six-character label. 



Responses 

DMSFOR603R FORMAT WILL ERASE ALL FILES ON DISK •mode(cuu) 1 . DO IOD WISH 
TO CONTINUE? (YES | WO): 

Tou have indicated that a disk area is to be initialized: any 
existing files will be erased. This message gives you the option 
of canceling the execution of the FORMAT command. Reply YES or 
NO. 

DMSFOR605R ENTER DISK LABEL: 

You have reguested that a label be written on the disk. Enter a 
one- to six-character label. 

DMSFOR705I DISK REMAINS UNCHANGED 

The response to message, DHSFOR603R, was *N0*. 

DMSFOR732I »nnn» CYL FORMATTED ON DISK • mode (ecu) • 

A formatting operation has been done on nnn cylinders of the disk 
at virtual address ecu. 

DMSF0R733I FORMATTING DISK »mode» 

The disk represented by mode letter 'mode 1 is being formatted. 

DISK 'mode (cuu) « : «n« FILES, »n« BLOCKS, »n» LEFT (OF , n»)# nnX FULL 
(»n» CYL) 

This message gives the extent and other information about a disk 
when a RECOMP operation has been done. 
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Other Messages and Return Co des 

DHSFOR003E IHVALID OPTIOH •option 1 RC=24 

DMSFOR017E INVALID DEVICE ADDRESS •cuu« RC=24 

DMSFOR028E HO DEVICE SPECIFIED RC-24 

DHSFOR037E DISK • iode[ (CUU) ]• IS READ/OHLI RC=36 

DHSFOR048E INVALID MODE •■ode 1 RC=24 

DHSFOR069E DISK •■ode 1 HOT ACCESSED RC=36 

DMSFOR070E IHVALID PARAMETER •paraa 1 RC=24 

DMSF0R113S cuu HOT ATTACHED RC=100 

DMSFOR114S •cuu» IS AH UHSOPPORTED DEVICE TYPE RC=88 

DHSFOR125S PERMAHEHT UHIT CHECK OH DISK •■ode (cuu) • RC-100 

DMSFOR126S ERROR { READ |WRIT}IHG LABEL OH DISK •■Ode(cuu)* RC=100 

DHSFOR214W CAHHOT RECOMPUTE WITHOUT LOSS OF DATA. HO CHAH6E RC=8 
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GENDIRT 

Use the GEHDIBT command to create a CHS auxiliary directory. The 
auxiliary directory contains the name and location of modules which 
would otherwise significantly increase the size of the resident 
directory, thus increasing search time and storage requirements. By 
using GEHDIBT to create an auxiliary directory, the file entries for the 
given command are loaded only when the command is invoked. The format 
of the GEHDIBT command is: 



i 

| GEHDIBT | directoryname [targetmode] 



where: 

directoryname is the entry point of the auxiliary directory. 

targetmode is the filemode letter of the disk containing the 

modules referred to in the directory. The letter is 

the filemode of the disk containing the modules at 

execution time, not the filemode of the disk at 

creation of the directory. The default value for 

targetmode is S, system disk. It is your 

responsibility to determine the usefulness of this 

I operand at your installation, and to inform all users 

| whose programs are in auxiliary directories exactly 

I what filemode to specify on the ACCESS command. 

Hote: See the VH/370: System Programmer' s Guide for information on 
creating auxiliary directories and for further requirements for using 
the targetmode option. 



Error Messages and Betnrn Codes 



DHSGHD002W FILE * f n ft fm* HOT FOUHD BC=4 
DHSGHD021E EHTBI POIHT •name* HOT FOUHD BC-28 
DHSGHD022E HO DIBECTOBT HAHB SPECIFIED BC=24 
DHSGHD070E IHVALID PAHAHETEB «param» BC=24 
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Use the GENMOD command to generate absolute core-image files, 
format of the GENMOD command is: 



The 



Genaod 



[fn [ft [f«]]] [ (options. ..[)]] 

options; [ FROM entry 1 ] 
[TO entry 2 ] 
r t 

I MAP I 

| NOMAP | 

L J 

r i 
| STB | 
| NOSTR | 

L J 

[ SYSTEM ] 



where; 
fn 

ft 
fn 



is the filename of the MODULE file being created. If fn is 
not specified, the file created has a filename equal to that 
of the first entry point in the LOAD HAP. 



is the filetype of the MODULE 
specified, ft must be MODULE. 



file being created. If 



is the filemode of the MODULE file being created. If fm is 
not specified, the file is written on the primary read/write 
disk. 



Options 



If conflicting options are specified, the last one entered is used. 

FROM entry 1 specifies an entry point or a control section name, which 
is the starting virtual storage location from which the 
core-image copy is generated. 

If FROM is not specified, the starting virtual storage 
location of the module is either the address of fn (if it 
is an external name) , or the address of the first 
external name encountered during the loading process.. 
This is not necessarily the lowest address loaded. If 
you have any external references before your START or 
CSECT instructions, you must specify FROM entryl to load 
your program properly. 

TO entry2 specifies an entry point or a control section name, which 
is the ending virtual storage location from which the 
core-image copy is generated. 

MAP includes a load map in the MODULE file. 

NOMAP specifies that a load map is not to be contained in the 
MODULE file. 
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GENMOD 



STR 



NOSTR 



SYSTEM 



Mote: If a module is generated with the NOMAP option, 
that module cannot later be loaded and started with the 
CMS LCADMOD and START commands. When NOMAP is specified, 
the information produced is not sufficient for the START 
command to execute properly. However, a module generated 
with the NOMAP option can later be invoked as a command, 
that is, it can be invoked if its filename is entered. 

invokes the CMS storage initialization routine when the 
MODULE is subseguently loaded (see the CMS LOADMOD 
command) . This routine frees any storage remaining from 
a previous program. STR is the default setting if the 
MODULE is to be loaded at the beginning of available user 
storage. 

indicates that, when the MODULE is loaded, free storage 
pointers are not reset for any storage currently in use. 
NOSTR is the default setting if the MODULE is to be 
loaded at a location other than the default load 
address. 

indicates that when the MODULE is subseguently loaded, it 
is to have a storage protect key of zero. 



Notes : 

1. Before the file is written, undefined symbols are set to location 
zero and the common reference control section is initialized. The 
undefined symbols are not retained as unresolved symbols in the 
MODULE file. Therefore, once the MODULE file is generated, those 
references cannot be resolved and may cause unpredictable results 
during execution. 

2. If you load a program into the transient area you should issue the 
GENMOD command with the STR option. Be careful if the program 
issues OS GETMAIN or FREEMAIN because your program, plus the amount 
of storage obtained via GETMAIN, cannot exceed two pages (8192K) . 
It is recommended that you do not issue a GETMAIN from a transient 
area. 



Error Messages and Return Codes 



DMSMCD001E NO FILENAME SPECIFIED RC=24 

DMSM0D002E FILE • f n ft' NOT FOUND RC=28 

DMSMOD003E INVALID OPTION 'option' RC=2U 

DMSMOD005E NO (FROM TO) ENTRY SPECIFIED RC=24 

DMSMCD021E ENTRY POINT 'name' NOT FOUND RC = 40 

DMSMOD032E INVALID FILETYPE 'ft' RC=24 

DMSMOD037E DISK 'mode' IS READ/ONLY RC=36 

DMSMOD040E NO FILES LOADED RC=U0 

DMSMOD070E INVALID PARAMETER '...• RC=24 

DMSMOD084E INVALID USE OF 'FROM* AND 'TO' OPTIONS RC=2U 

DMSM0D105S EBROR 'nn' WRITING FILE ' f n ft fm' ON DISK RC=100 

DMSMOD109S VIRTUAL STORAGE CAPACITY EXCEEDED RC=104 
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Use the GLOBAL command to specify which CMS libraries are to be searched 
when processing subsequent CHS commands. The GLOBAL command remains in 
effect for an entire CMS session unless it is explicitly canceled or 
until another GLOBAL command is entered. There are no default 
libraries, so the command must be libraries if any libraries are to be 
used. The GLOBAL command verifies the existence of the libraries and 
issues a warning message if a specified library does not exist. The 
format of the GLOBAL command is: 



I MACLIB \ [libnamel ... Iibname8 ] | 

\ TXTLIB ) I 



where : 

MACLIB allows the specification of the macro libraries that are 
to be used during the execution of language processor 
commands. The macro libraries may be CMS files or OS 
data sets. If you specify an OS data set, FILEDEF must 
be issued for the data set before you issue GLOBAL. (See 
the description of the FILEDEF CONCAT option for more 
information.) 

TXTLIB allows the specification of text libraries to be searched 
for missing subroutines when the LOAD or INCLUDE command 
is issued, or when a dynamic load occurs (that is, when 
OS SVC 8 is issued) . 

Note: Subroutines that are called by dynamic load should 
(1) contain only VCONs that are resolved within the same 
text library member or (2) be resident in storage 
throughout the processing of the original CMS LOAD or 
INCLUDE command. Otherwise, the entry point is 
unpredictable. 

libnamel... is the filename of up to eight libraries. If the MACLIB 
form of the GLOBAL command is used, the filetypes of all 
files specified must be MACLIB. If the TXTLIB form of 
the command is used, the filetypes of all files specified 
must be TXTLIB. The libraries are searched in the order 
in which they are named. If no library names are 
specified, the command cancels the effect of any previous 
GLOBAL command. 

If you want to use an OS library during the execution of a language 
processor, you can issue a GLOBAL command to access the library, as long 
as you have defined the library via the FILEDEF command. If you want to 
use that library for more than one job, however, you must redefine it 
tagain, via FILEDEF) , since the language processors clear your previous 
definition of the library. 

Another means for reusing a library is the PERM option of the FILEDEF 
command. If you use PERM, you must clear that FILEDEF before you issue 
another GLOBAL for a different library. 
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GLOBAL HACLIB ACCESS STSHAC 

The systei searches the ACCESS HACLIB and SYSHAC HACLIB files for 
■issing lacros during compilations. 

GLOBAL TXTLIB CONVERT FLOAT 

The systei searches the COEYEBT TXTLIB and FLOAT TXTLIB files for 
■issing subroutines during subseguent LOAD and INCLUDE operations. 

GLOBAL HACLIB 
Cancels the effect of any previous GLOBAL HACLIB libnaie connand. 



Error Messages and Return Codes 



DHSGLB0021 FILE *fn ft* EOT FOUHD RC=28 
DHSGLB014E INVALID FOHCTIOH 'function* RC=2U 
DHSGLB047E 10 FOMCTIOH SPECIFIED HC=24 
DHSGLB108S HORE TBAH 8 LIBRARIES SPECIFIED RC-88 
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Use the IHCLODE coaaand to read one or more TEXT files (containing 
relocatable object code) froi disk and to load thea into storage, 
establishing the proper linkages between the files. INCLUDE is normally 
used to resolve references left unresolved by a previous LOAD or INCLUDE 
command. Refer to Figure 21 for a description of the handling of 
unresolved references. A LOAD coaaand Bust have been previously issued 
for the IHCLUDE coaaand to produce desirable results. The foraat of the 
INCLUDE coaaand is: 



include | fn... [ (options. ..[)] ] 
options : r 



ICLBAR | 
INOCLEABI 



I 



RESET 



entry) | [ORIGIN hexloc] 



r i 

I MAP | 
|NOHAF| 
i j 

r n 

ILIBE | 
|NOLIBE| 
i j 



r •% 

ITYPE | 
IN0TYPE1 



r t 

iisi i 

|NOINV| 

L J 



[START] [SAME] 



r i 

IB!! I 
|NOREP| 

L J 

r t 

|NODUP| 

L J 



I AUTO | 
|NOAUTO| 

L J 



where; 
fn. . . 



are the names of the files to be loaded into storage. 
Files aust have a filetype of TEXT and consist of 
relocatable object code such as that produced by the 
language processor coaaands. 



Options 



If options were specified with a previous LOAD or INCLUDE coaaand, 
these options (with the exception of CLEAR and ORIGIN) reaain set if 
SAME is specified when INCLUDE is issued. Otherwise, the options 
assuae their default settings. If conflicting options are specified, 
the last one entered is in effect. 



CLEAR 



clears the load area in storage to binary zeros before 
the files are loaded. 



NOCLEAR 



does not clear the load area before loading. 



RESET (entry 1 resets the execution starting point previously 
\ * J set by a LOAD or INCLUDE coaaand. If entry is 
specified, the starting execution address is reset to 
the specified location. If an asterisk (*) is 
specified, the starting point is reset to the location 
of the first file or to the address specified as an 
operand of an END card, LDT card, or ENTRY card. 

ORIGIN hexloc begins loading the prograa at the location specified 
by hexloc. The variable, hexloc, is a hexadeciaal 
number of up to eight characters. If this option is 
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MAP 

NOMAP 

TYPE 

NOTYPE 

INV 

HOIHV 

BEP 

HOHEP 

AUTO 

NOAUTO 
LIBE 

NOLIBE 

START 
SAME 



DDP 



NODDP 



not specified, loading begins at the next available 
storage location. INCLUDE does not overlay any 
previously loaded files unless this option is 
specified and the address given indicates a location 
within a previously loaded object module* 

adds information to the LOAD MAP file. 

does not add any information to the LOAD MAP file. 

displays the load map of the files at the terminal, as 
well as writing it on the primary disk. This option 
is valid only if MAP is specified or implied. 

does not display the LOAD MAP file at the terminal. 

prints invalid card images in the LOAD HAP file. 

does not print invalid card images in the LOAD MAP 
file. 

prints replace statement images in the LOAD MAP file. 
See the explanation of the CMS LOAD command for a 
description of the replace (BEP) statement. 

suppresses the printing of replace statements in the 
LOAD MAP file. 

searches your disks for TEXT files to resolve 
undefined references. 

suppresses automatic searching for TEXT files. 

searches the text libraries defined by the GLOBAL 
command for missing subroutines. 

does not search any text libraries for unresolved 
references. 

begins execution after loading is completed. 

retains the same options (except ORIGIN and CLEAB) 
that were used by a previous INCLUDE or LOAD command. 
Otherwise, the default setting of unspecified options 
is assumed. If other options are specified with SAME, 
they override previously specified options. See the 
examples. 

displays warning messages at your virtual console when 
a duplicate CSECT is encountered during processing. 
The duplicate CSECT is not loaded. 

does not display warning messages at your virtual 
console when duplicate CSECTs are encountered during 
processing. The duplicate CSECT is not loaded. 
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| Use standard order of search to | 
| locate the TEXT files specified | 
| by fn ... | 

i i 

I 



. * Any * 
unresolved 
references 
? 

* . . * 

|YES 

I 

. * . 

. * Is * 

HOAUTO 

specified 

? 

* . . * 

* 

| NO 

I 



* . NO 
. * 



* . YES 
. * 



Use standard order of search to 
locate files with a filetype of 
TEXT and a filename correspond- 
ing to the unresolved reference 



,< 

i 
. * . 

. * Any * . 

* unresolved * 
references 

* . ? . * 

* . . * 

|YES 

I 

. * . 
. * Is * . 

* HOLIBE * 
specified 

* . ? . * 

* . . * 

| NO 
I 



NO 



YES 



Search active text libraries 
(those that were previously 
specified by a GLOBAL command) . 
Files are searched in the order 
they are entered in the command. 



| Search | 
| terminated j 
i i 



| Search | 
| complete | 



I Search | 
| complete | 

i , ,i 



| Search terminated | 

t .,.., . j 



Figure 21. Resolution of Unresolved References 



152 IBM VM/370: Command Language Guide for General Users 



GC20-1804-3 Page Modified by TNL GN20-2659 

INCLUDE 

Examples 

INCLUDE MAIN SUBI DATA (RESET MAIN MAP STABT) 

Brings the files named MAIN TEXT, SUBI TEXT, and DATA TEXT into real 
storage and appends them to files which were previously loaded. 
Information about these loaded files is added to the LOAD MAP file. 
Execution begins at entry point MAIN. 

LOAD MYPROG (NOMAP NOLIBE NOREP) 

INCLUDE MYSUB (MAP SAME) 

During execution of the LOAD command, the file named MYPROG TEXT is 
brought into real storage. The following options are in effect: NOMAP, 
NOLIBE, NOREP, NOTYPE, IN?, AUTO. During execution of the INCLUDE 
command, the file named MYSUB TEXT is appended to MYPROG TEXT. The 
following options are in effect: 

MAP, NOLIBE, NOREP, NOTYPE, INV, AUTO 

Note: After you IPL CMS, at least one LOAD command must be issued before 
INCLUDE can be used with predictable results. 



Responses 

DMSLI0740I EXECUTION BEGINS... 

START was specified with INCLUDE and the loaded program has begun 
execution. Any further responses are from the program. 

INVALID CARD - XXX...XXX 

INV was specified with LOAD and an invalid card has been found. 
The message and the contents of the invalid card (xxx...xxx) are 
listed in the file LOAD MAP. The invalid card is ignored and 
loading continues. 

CONTROL CARD - ... 

A loader or library-search control statement was encountered (that 
is, ENTRY or LIBRARY) . See the description of the LOAD command for 
the use of ENTRY and LIBRARY control cards. This response is 
placed in the LOAD MAP file only. 



Other Messages and Return Codes 

DMSLI0001E NO FILENAME SPECIFIED RC = 24 

DMSLIO002E FILE 'fn ft' NOT FOUND RC=28 

| DMSLIC003E INVALID OPTION 'option' RC=2U 

DMSLI0005E NO option SPECIFIED RC=24 

DMSLI0021E ENTRY POINT 'name' NOT FOUND RC=40 

DMSLIO029E INVALID PARAMETER 'param' IN THE OPTION 'option' FIELD RC=2U 

DMSLI0055E NO ENTRY POINT DEFINED RC=40 

DMSLIO056E FILE ' f n ft' CONTAINS INVALID RECORD FORMATS RC=32 
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DMSLI0104S EEEOE 'nn' READING FILE • f n ft fm« FROM DISK RC=100 

DMSLIO105S ERROR 'nn' WRITING FILE • f n ft f m ' ON DISK RC=100 

DMSLI0109S VIRTUAL STORAGE CAPACITY EXCEEDED RC=104 

DMSLI0116S LOADER TABLE OVERFLOW RC=10U 

DMSLI0168S PSEUDO REGISTER TABLE OVERFLOW RC=10U 

DMSLI0169S ESDID TABLE OVERFLOW RC=104 

DMSLIO201W THE FOLLOWING NAMES ARE UNDEFINED: RC=4 

DMSLIO202W DUPLICATE IDENTIFIER 'identifier 1 RC=4 

DMSLIO203W "SET LOCATION COUNTER" NAME 'name' UNDEFINED RC=4 

DMSLIO206W PSEUDO REGISTER ALIGNMENT ERROR RC=4 

DMSLIO907T I/O ERROR ON FILE « f n ft fm' RC=256 
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7.7STDS 



Use the LISTDS command to list at your terminal information describing 
the data sets residing on an OS disk, or the files on a DOS disk. 

The format of the LISTDS command is: 



LISTDS 



r t 

! ? | (fu) [ (options. ..[) ]] 
|dsname| \ * ] 



op t ion s : 
[FORMAT] 
[PDS ] 



where : 



indicates that you want to enter the OS data set name or DOS 
file-id from your terminal. If you enter the guestion mark 
(?) , CMS reguests that you enter the OS data set name or DOS 
file-id exactly as it appears in the data set or file. Do 
not omit the periods that separate the gualifiers of an OS 
data set name, but do not insert periods where they do not 
appear. 

gual1[ .gual2.gualn ] 

where guall, gual2, through gualn are gualifiers for the data 
set name or file-id. Using this form, you can specify data 
set names or file-ids that contain embedded special 
characters such as blanks and hyphens. 



dsname 



is the OS data set name or DOS file-id and takes the form: 



gual1[ gual2 gualn] 

where guall, gual2, through gualn are the gualifiers for the 
data set name or file-id. Each gualifier must not exceed 8 
characters and must be separated from other gualifiers by 
blanks, not periods. (This form can be used for DOS file-ids 
only if they comply with the OS naming convention of one- to 
eight-byte gualifiers separated by periods, to a maximum of 
44 characters, including periods.) For example, for an CS 
data set or DOS file named MY. FILE. IN, you enter: 

LISTDS MY FILE IN 



fm 



is the filemode of the data set or file being listed. 



indicates that you want the data set name (or file-id) and 
filemode listed for all of the data sets (or files) on all of 
the OS or DOS disks currently accessed. 
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Options 



FORMAT 
FO 



PDS 



displays the date, disk label, filemode, and data set name for 
the OS data set as well as the BECFM, LRECL, BLKSIZE, and 
BSORG operands. For a DOS file, LISTDS displays the date, 
disk label, filemode, and file-id, but gives no information 
about the RECFM, LRECL, and BLKSIZE operands (two blanks 
appear for each) ; DSOBG is always PS. 



displays the member names of references 
access Method (PAM) data sets. 



to OS Partitioned 



Example 



The following is an example of LISTDS with the FORMAT and PDS options 
and the output resulting from the command. 



listds d (fo pds) 

RECFM LRECL BLKSI DSOBG DATE LABEL FM 

FB 80 800 PO 01/31/75 OSSYS1 D 
MEMBER NAMES: 

ABEND ATTACH BLDL BSP CLOSE 

FIND PUT READ WRITE XDAP 

RECFM LRECL BLKSI DSOBG DATE LABEL FM 



80 



80 



PS 01/10/75 055Y51 



DATA SET NAME 
SYS1.MACLIB 

DCB DETACH 

DATA SET NAME 
SAMPLE 



DEVTYPE 



Response 



DMSLDS220R ENTER DATA SET NAME: 



The LISTDS command with the ? operand was issued. Enter an OS data 
set name in the form guall . gual2. gualn; where quail, qual2, through 
qualn are the qualifiers of the OS data set name. 



2£!l§£ Hii§§il3§§ <m<l Upturn Codes 



DMSLDS002E DATA SET NOT FOUND RC=28 

DMSLDS003E INVALID OPTION 'option' RC=24 

DMSLDS048E INVALID MODE 'mode' RC=2U 

DMSLDS069E DISK 'mode' NOT ACCESSED RC=36 

DMSLDS221E INVALID DATA SET NAME RC=24 

DMSLDS222E I/O ERROR READING 'data set name' FROM OS DISK RC=28 

DMSLDS223E NO FILENAME SPECIFIED RC=2U 

DMSLDS231E I/O ERROR READING VTOC FROM ...-DISK (OS) RC=28 
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USTFILE 



Use the LISTFILE command to obtain specified information about your CHS 
files residing on accessed disks. The information may be either 
displayed at the terminal or used to create a special EXEC file on 
disk. All operands are optional; if no operands are specified, a list 
| of default information about each file on your primary read/write disk 
is displayed at the terminal. The format of the LISTFILE command is: 




r r r m 

|fn |ft IfmlM 

I* I* I* III 

L L L JJJ 



[ (options.. .[) ]] 



option s; 



r i 

| Header | 
|HOHeader| 

L J 



r t 

| Exec | 
| APpend | 



r 

|FName 

IFType 

IFHode 

| FOrmat 

lALloc 

| Date 

ILabel 

L 



where; 
fn 



is the filename of the files 
collected. If an asterisk 
filenames are used. 



for which information is to be 
is coded in this field, all 



ft 



fm 



is the filetype of the files for which information is to be 
collected. If an asterisk is coded in this field, all 
filetypes are used. 

is the filemode of the files for which information is to be 
collected. If this field is omitted, only the primary disk is 
searched* If an asterisk is coded, all disks are searched. 



Bote: An asterisk (*) , immediately preceded by any number of characters 
for fn or ft, searches for the specified characters as the leading 
characters for that identifier. For example, LISTFILE ABC* ASSEHBLE 
prints the identifiers for all ASSEHBLE files with filenames beginning 
with ABC. 



Output Format Options 



HEADER includes column headings in the listing. HEADER is the 
default if any of the "Supplemental Information" options 
are specified. The format of the heading is: 

FILENAHE FILETTPE FH FORHAT RECS BLOCKS DATE TIHE LABEL 



HOHEADER does not include column headings in the list. HOHEADER is 
the default if only filename, filetype, or filemode 
information is requested. 
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Outfit DigEosi tion Options 



EXEC creates a file of 80-character records (one record for each 
of the files which satisfies the given file identifier) on 
the primary disk. The file that contains these records is 
called CHS EXEC A1. If a file with this naie already 
exists, the existing one is erased and a new one is created 
(unless the APPEND option is specified, in which case the 
existing file is retained and the new entries are appended 
to it) . The EXEC procedure thus created contains two 
symbolic variables, 81 and 62. This CHS EXEC file is used 
with the EXEC command, but it can also be processed as any 
other file (that is, printed, displayed, edited, added to, 
changed, and so forth). The header is not included in the 
file. 

APPEND appends the EXEC list created to the existing CHS EXEC A1 
file. If the EXEC option is specified instead of APPEND, 
any existing CHS EXEC file is erased and replaced by the 
file created by this LISTFILE command. If this option is 
specified and no CHS EXEC file exists, one is created. 

Information Reques t O ptions 

Only one of these options need be specified. If one is specified, 
any options with a higher priority are also in effect. If none of 
the following options are specified, the default information request 
options are in effect. 

Default Information Request Options 

FNAHE creates a list containing only filenames. Option priority 
is 7. 



FTYPE 



FHODE 



creates a list containing only filenames and filetypes. 
Option priority is 6. 

creates a list containing filenames, filetypes, and 
filemodes. Option priority is 5. 



Supplemental Information Options 

FORHAT includes the record format and logical record length of the 
of each file in the list. Option priority is 4. 

ALLOC includes the amount of disk space that CHS has allocated to 
the specified file in the list. The quantities given are 
the number of 800-byte blocks and the number of logical 
records in the file. Option priority is 3. 

DATE includes the date the file was last written in the list. 
The form of the date is: 

month/day/year hour: minute 

Option priority is 2. 

LABEL includes the label of the disk on which the file resides in 
the list. Option priority is 1. 
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Example 

LISTFILE * ASSBMBLE * (LABEL) 

LABEL is th© 1g**SS+" '"*'»~XGrX'*"ff nrtiftri' tKorofrire. all n-f-hoT rm+inne: are 

also in effect. All information about the files with a filetype of 
ASSEMBLE is displayed at the terminal. The header is displayed because 
LABEL is a supplemental information option. 

The following is displayed at the terminal: 

FILENAME FILETTPE FH FORMAT RECS BLOCKS DATE TIME LABEL 

r t 
|F| 
fn ASSEMBLE fm |v| lrecl norecs noblks mm/dd/yy hh:mm volid 



One entry is displayed for each file with a filetype of ASSEMBLE, 
where: 

fn is the filename of the file. 

ASSEMBLE is the filetype specified in the command. 

fm is the filemode of the file. 

r t 

|F| is the file format: F = fixed length 
|? | V = variable length 

L J 

lrecl is the logical record length of the largest record in the 
file. 

norecs is the number of logical records in the file. 

noblks is the number of physical blocks that the file occupies on 
disk. 

mm/dd/yy is the date (month/day/year) that the file was created. 

hh:mm is the time (hours: minutes) that the file was created. 

volid is the volume serial number of the virtual disk on which 
the file resides. 



Responses 

If the EXEC option is not specified, the reguested information is 
displayed at the terminal. 
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Error Messages and Return Codes 

DMSLST002E FILE NOT FOUND HC=28 

DHSLST003E IBVALID OPTION 'option 1 RC=24 

DMSLST037E DISK •■ode* IS READ/ONLY RC=36 

DMSLST048E IBVALID MODE •■ode 1 RC=2U 

DHSLST066E • option* and 'option* ARE CONFLICTING OPTIONS RC=24 

DHSLST069E DISK *«ode* HOT ACCESSED RC=36 

DMSLST070E INVALID PARAMETER *parai* RC=24 

DHSLST105S ERROR »nn • WRITING FILE * f n ft £■• ON DISK RC=100 

| Note; Tou can invoke the LISTFILE conand froa the terminal, froi an 

| EXEC file, or as a function froi a prograi. If LISTFILE is invoked as a 

| function or froa an EXEC file that has the 6C0NTR0L NOHSG option in 

| effect, the DHSLST002E FILE NOT FOUND error message is not issued. 
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LOAD 



Use the LOAD command to read one or more TEXT files (containing 
relocatable object code) from disk and to load them into virtual 
storage, establishing the proper linkages between the files. 

Notes; 

1. The LOAD command reguires a read/write A-disk to contain a work 
file. 

2. If you are loading a program into the transient area see Note 2 for 
the GENNOD command. 

The format of the LOAD command is: 



LOAD 



fn 



oj3 1 ions : 



[ (options. . . [) ]] 



r i r i r 

ICLEAR | |RESET JentryU |ORIGIN 
|NOCLEAR| | \ * J | | 



( hexloc) j 
\ TRANS J| 



I MAP | 
|NOMAP| 

L J 

r i 
|NOLIBE| 



ITYPE | 
|NOTYPE| 

L J 

[START] 



\w 1 

|NOINV| 

L J 

r l 

IDUP | 
|NODUP| 



r t 

I REP | 
|NOREP| 

L J 



r t 

I AUTO | 
|NOADTO| 

L J 



w her e : 

fn... specifies the names of the files to be loaded into storage. The 
files must have a filetype of TEXT and consist of relocatable 
object code such as that produced by the language processors. 

Note: If you have a program that issues a dynamic load command 
(OS SVC 8) for a subroutine that (1) is a CSECT in a CMS text 
library member and (2) contains VCONs • for entry points not in 
the same member, that subroutine must be explicitly loaded with 
the program that uses it. Otherwise, the entry point returned 
by the CMS LOAD command is unpredictable. 



Options 



If conflicting options are specified, the last one entered is in 
effect. 



CLEAR clears the load area in storage to binary zeroes before the 
object files are loaded. 



NOCLEAR does not clear the load area before loading. 



RESET ( entry 1 



sets the starting location for the programs currently loaded. 
The operand, entry, must be an external name (for example, 
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CSECT or EHTBY) in the loaded programs. If RESET is not 
specified, the default entry point is either (1) the entry 
point of the first file loaded, (2) the address on an END 
card, (3) the location of a name occurring on an LDT card, or 
(4) the location of the operand on an EHTBY statement. If * 
is entered the results are the same as if the RESET option 
were omitted. 



ORIGIN 



| hexloc ) 
\TRANS ) 



loads the program beginning at the location specified by 
hexloc; this location must be in the CMS nucleus transient 
area or in the user area. The location, hexloc, is a 
hexadecimal number of up to eight characters. If TRANS is 
specified, the file is loaded into the CMS nucleus transient 
storage locations. If this option is not specified, loading 
begins at the first available user storage location. 

Note: Any program loaded into the transient area must have a 
starting address of X'EOOO'. 



MAP creates the file LOAD MAP on the primary disk. 
NOMAP does not create the file LOAD MAP. 



TYPE displays the LOAD MAP file at the terminal. This option is 
valid only if the MAP option is in effect. 

NOTYPE does not display the LOAD MAP file at the terminal. 



INV 



REP 



includes the invalid card images in the LOAD MAP file. 



NCINV does not include the invalid card images in the LOAD MAP 
file. 



includes the replace statements in the LOAD MAP file. 



NCREP does not include the replace statements in the LOAD MAP 
file. 



AUTO searches your virtual disks for TEXT files to resolve 
undefined references. 

NOAUTO suppresses automatic searching for TEXT files. 



LIBE searches the text libraries for missing subroutines. If text 
libraries are to be searched for TEXT files, they must 
previously have been defined by a GLOBAL command. 



NCLIBE does not search 
references. 



the 



text 



libraries for 



unresolved 



START executes the program being loaded when leading is completed. 
LOAD does not normally begin execution of the loaded files. 
To begin execution immediately upon successful completion of 
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loading, START can be specified. LOAD then transfers control 
to an entry point in the program. The default entry point is 
(1) the address specified in the operand field of the first 
END statement containing a non-blank operand field, (2) the 
address of a name on an LDT statement, (3) the beginning of 
the first file loaded (if all END statements in the TEXT 
files contain blank operand fields) , or (4) the ENTRY 
specified. 

DUP displays warning messages at your terminal when a duplicate 
CSECT is encountered during processing. The duplicate CSECT 
is not loaded. 

NODUP does not display warning messages at your terminal when 
duplicate CSECTs are encountered during processing, The 
duplicate CSECT is not loaded. 

FILES CREATED BY THE LOAD COMMAND; The LOAD command produces one 
temporary workfile: 

DMSLDR SYSUT1 

This temporary work file is placed on the read/write A-disk, which must 
be available. 

LOAD MAP FILE; Unless the NOMAP option is specified, a load map is 
created on the primary disk each time the LOAD command is issued. A 
load map is a file that contains the location of control sections and 
entry points of files loaded into storage. It may also contain messages 
and card images for invalid cards or replace cards that exist in the 
loaded files. This load map is normally created as a file with the file 
identification LOAD HAP. Only one such file may exist on the primary 
disk. Each time LOAD is issued, a new LOAD MAP file replaces any 
previous LOAD MAP file. 

If invalid card images exist in the file or files that are being 
loaded, they are listed with the message INVALID CARD in the LOAD MAP 
file* To suppress this listing in the load map, the NOINV option must 
be specified. 

If replace (REP) statements exist in the file being loaded, they are 
included in the LOAD MAP file. To suppress this listing of REP 
statements, the NOREP option must be specified. 

DP PLICATE CSECTS; Duplicate CSECTs (control sections) are bypassed by 
the loader. Cnly the first CSECT encountered is physically loaded. The 

| duplicates are not loaded. A warning message is displayed at your 

I terminal if you specified the DUP option. 

LOADER CONTROL STATEMENTS; Five types of control statements can be added 
to a TEXT file. These are the set location counter (SLC) , the include 
control section (ICS) , the replace (REP) , the ENTRY, and the LIBRARY 
statements. These are used to set the virtual storage location where 
the LOAD command begins placing the file, to make corrections and 
additions to the relocatable object code in virtual storage once the 
file is loaded, to specify entry points, and to specify references that 
are not to be resolved. These statements can be added to the TEXT files 
already punched and can then be read back in, or they can be added using 
the EDIT command. 
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Set Location Counter (SLC) Statement: The SLC statement sets the 
location counter used with the loader. The file loaded after the SLC 
statement is placed in virtual storage beginning at the address set by 
this SLC statement. The SLC statement has the format shown in Figure 
22. It sets the location counter in one of three ways: 

1 . With the absolute virtual address specified as a hexadecimal number 
in columns 7-12. 

2. With the symbolic address already defined as a program name or 
entry point. This is specified by a symbolic name punched in 
columns 17-22. 

3. If both a hexadecimal address and a symbolic name are specified, 
the absolute virtual address is converted to binary and added to 
the address assigned to the symbolic name; the resulting sum is 
the address to which the loaders location counter is set. For 
example, if 0000F8 was specified in columns 7-12 of the SLC card 
image and GAMMA was specified in columns 17-22, where GAMMA has an 
assigned address of 006100 (hexadecimal) , the absolute address in 
columns 7-12 is added to the address assigned to GAMMA giving a 
total of 0061F8. Thus, the location counter would be set to 
0061F8. 

If there are blanks in both columns 7-12 and 17-22, or the symbolic 
name has not yet been defined, the response INVALID CARD xxx...xxx 
is displayed or, depending on the option (NOINV or INV) specified, 
is written in the LOAD MAP file. If only the symbolic address is 
to be used, columns 7-12 must be left blank or be all zeros. If 
only the absolute address is to be used, columns 17-22 must be left 
blank. 



| Column 


Contents I 


| 1 


I Load control statement identification (12-2-9 punch). | 
Identifies this as a statement acceptable to the loader. | 


| 2-4 


SLC — identifies the type of load statement. j 


| 5-6 


Blank. I 


I 7-12 


Hexadecimal address to be added to the value of the symbol, | 
if any, in columns 17-22. It must be right-justified in | 
these columns, with unused leading columns filled with | 




zeros. I 


I 13-16 


Blank. I 


I 17-22 


Symbolic name whose assigned location is used by the j 
loader. Must be left- justified in these columns. If blank, | 
the address in the absolute field is used. | 


I 23 


Blank. I 


I 24-72 


May be used for comments or left blank. j 


| 73-80 


Not used by the loader. You may leave these columns j 
blank or insert program identification for your own | 




convenience. I 



Figure 22. SLC Statement Format 
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Loader Terminate (LDT) Statement ; The LDT statement is used in a text 

library as the last record of a member. It indicates to the loader that 

all records for that member were processed. The LDT statement can 

contain a name to be used as the entry point for the loaded member. The 

I. DT 'statSIgn*' liae +Ko format cKrun -in Pi <tiit*o O 3 



Column | 



Contents 



1 I Load control statement identication (12-2-9 punch). 

Identifies this as a statement acceptable to the loader. 

2-4 | LDT — identifies type of statement. 

5-16 i Hot used. 

17-24 | Blank or entry name (left justified padded with blanks to 
8 characters) . 

25-80 I Not used. 



Figure 23. LDT Statement Format 



Include Control Section (ICS) Statement; The ICS statement changes the 
length of a specified control section or defines a new control section. 
It should be used only when REP statements cause a control section to be 
increased in length. The format of an ICS statement is shown in Figure 
24. An ICS statement must be placed at the front of the file or TEXT 
file. 



| Column 


Contents | 


I 1 


Load control statement identification (12-2-9 punch) . | 
Identifies this as a statement acceptable to the loader. | 


| 2-4 


I ICS — identifies the type of load statement. | 


| 5-16 


Blank. j 


| 17-22 


Control section name — left- justified in these columns. | 


| 23 


Blank. I 


I 24 


, (comma) . I 


I 25-28 


Hexadecimal length in bytes of the control section. This j 
must not be less than the actual length of the previously | 
specified control section. It must be right— justified in | 
these columns with unused leading columns filled with | 
zeros. j 


I 29 


Blank. I 


| 30-72 


Hay be used for comments or left blank. I 


| 73-80 


Hot used by the loader. You may leave these columns blank | 
or insert program identification for your own convenience. | 



Figure 24. ICS Statement Format 
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!§£lace (REP) Statement: A REP statement allows instructions and 
constants to be changed and additions made. The REP statement must be 
punched in hexadecimal code. The format of a REP statement is shown in 
Figure 25. The data in columns 17-70 (excluding the commas) replaces 
what has already been loaded into virtual storage, beginning at the 
address specified in columns 7-12. REP statements are placed in the 
file either (1) immediately preceding the last statement (END statement) 
if the text deck does not contain relocatable data such as address 
constants, or (2) immediately preceding the first RLD (relocatable 
dictionary) statement if there is relocatable data in the text deck. If 
additions made by REP statements increase the length of a control 
section, an ICS statement, which defines the total length of the control 
section, must be placed at the front of the deck. 



Column | 



Contents 



1 I Load control statement identication (12-2-9 punch) . 

Identifies this as a statement acceptable to the loader. 

2-4 I REP — identifies the type of load statement. 

5-6 | Blank. 

7-12 I Hexadecimal starting address of the area to be replaced as 
assigned by the assembler. It must be right- justified in 
in these columns with unused leading columns filled with 
zeros. 

13-1U I Blank. 

15-16 I ESID (External Symbol Identification) — the hexadecimal 

number assigned to the control section in which replacement 
is to be made. The LISTING file produced by the compiler 
or assembler indicates this number. 

17-70 | A maximum of 11 four-digit hexadecimal fields, separated by 
commas, each replacing one previously loaded half word (two 
bytes). The last field must not be followed by a comma. 

71-72 I Blank. 

73-80 I Not used by the loader. This field may be left blank or 
program identification may be inserted. 

■ , , ,. „ ■■■.,, . ,. ,, 

Figure 25. REP Statement Format 



ENTRY Statement: The ENTRY statement specifies the first instruction to 
be executed. It can be placed before, between, or after object modules 
or other control statements. The format of the ENTRY statement is shown 
in Figure 26. The external name is the name of a control section or an 
entry name in the input deck. It must be the name of an instruction, 
not of data. 



| ENTRY | external name 



Figure 26. ENTRY Statement Format 



166 IBM VM/370: Command Language Guide for General Users 



LOAD 



The loader selects the entry point for the loaded program according 
to the following hierarchy: 

1. From the parameter list on the START command. 

2. From the last BESET operand in the LOAD or INCLUDE command 
entered. 

3. From the last ENTRY statement in the input. 

4. From the last LDT statement in the input. 

5. From the first assembler- or compiler-produced END statement that 
specifies an entry point if no ENTRY statement is in the input. 

6. From the first byte of the first control section of the loaded 
program if there is no ENTRY statement and no assembler— or 
compiler-produced END statement specifying an entry point. For 
example: 

ENTRY GO 

where GO is defined as the external name of the first instruction 
to be executed when the program is loaded. The address of the 
instruction, indicated by the symbolic name GO, is specified by the 
loader as the starting point of the program when it is executed. 

LIBRARY Statement: The LIBRARY statement can be used to specify the 
never-call function. The never-call function (indicated by an asterisk, 
*, as the first operand) specifies those external references that are 
not to be resolved by the automatic library call during any loader step. 
It is negated when a deck containing the external name referred to is 
included as part of the input to the loader. The format of the LIBRARY 
statement is shown in Figure 27. The external reference refers to an 
external reference that may be unresolved after input processing. It is 
not to be resolved. Multiple external references within the parentheses 
must be separated by commas. The LIBRARY statement can be placed 
before, between, or after object decks or other control statements. 



| LIBRARY 



* (external reference) | 



Figure 27. LIBRARY Statement Format 



Example 



LIBRARY * (SINE) 

The * specifies the never-call function. SINE is an external reference 
in the output. As a result, if SINE is unresolved after input 
processing, no automatic library call is made. 
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Responses 

| DHSLIO740I EXECUTION BEGINS... 

START was specified with LOAD and the loaded program starts 
execution. Any further responses are from the program. 

INVALID CARD - XXX...XXX 

INV vas specified with LOAD and an invalid statement vas found. 
The message and the contents of the invalid statement (xxx...xxx) 
are listed in the file LOAD HAP. The invalid statement is ignored 
and loading continues. 

CONTROL CARD - ... 

A loader or library -search control statement (that is, ENTRY or 
LIBRARY) was encountered. This response is placed in the LOAD HAP 
file. 



Other Messages and Return Code s 

DHSLI0001E NO FILENAHE SPECIFIED RC=24 

DHSLIO002E FILE • f n ft* HOT FOUND RC=28 

DHSLI0003E INVALID OPTION 'option* RC=2U 

DHSLIO00UE ENTRY POINT •name* NOT FOUND RC-40 

DHSLIO005E NO option SPECIFIED RC*24 

DHSLI0021E ENTRY POINT 'name* NOT FOUND RC-40 

DHSLI0029E INVALID PARAHETBR «param» IN THE OPTION 'option • FIELD RC=24 

DHSLI0055E NO ENTRY POINT DEFINED RC-40 

DHSLIO056E FILE 'fn ft* CONTAINS INVALID RECORD FORHATS RC=32 

DHSLI0104S ERROR *nn* READING FILE *fn ft fm* FRON DISK RC=100 

DHSLI0105S ERROR *nn* WRITING FILE *fn ft fm* ON DISK RC=100 

DHSLI0109S VIRTUAL STORAGE CAPACITY EXCEEDED RC=104 

DHSLI0116S LOADER TABLE OVERFLOW RC=104 

DHSLI0168S PSEUDO REGISTER TABLE OVERFLOW RC-104 

DHSLI0169S ESDID TABLE OVERFLOW RC=10ft 

DHSLIO201W THE FOLLOWING HANES ARE UNDEFINED: RC=4 

DHSLIO202W DUPLICATE IDENTIFIER 'identifier* RC=4 

DHSLIO203W "SET LOCATION COUNTER" NAHE 'name* UNDEFINED RC=1 

DHSLIO206W PSEUDO REGISTER ALIGNHENT ERROR RC=4 

DHSLIO907T I/O ERROR ON FILE *fn ft f m • RC=256 
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LOADMOD 



LOADMOD 

Use the LOADMOD command to bring a disk file into storage. The file 
must be in absolute core-image format as created by the GENMOD command. 
The format of the LOADMOD command is: 



i 1 

| LOADMod | fn [ft fm] I 

i i 



w her e : 

fn is the filename of the file to be loaded into storage. 

ft is the filetype of the file to be loaded. If supplied, the 
filetype must be MODULE. 

fm is the filemode of the module to be loaded. 

If filetype and filemode are not supplied, the standard order of search 
is used to locate a file with the specified filename and a filetype of 
MODULE. 



EJLL2E Messages and Return Codes 



DMSMOD001E NO FILENAME SPECIFIED RC=24 

DMSMOD002E FILE *fn ft' NOT FOUND RC=28 

DMSMOD032E INVALID FILETYPE 'ft' RC = 2U 

DMSM0D037E DISK 'mode' IS READ/ONLY RC=36 

DMSMOD040E NO FILES LOADED RC=40 

DMSMOD070E INVALID PARAMETER • param' RC=24 

DMSMCD104S ERROR ' nn • READING FILE ■ f n ft f m • FROM DISK RC=100 

DMSMOD109S VIRTUAL STORAGE CAPACITY EXCEEDED RC=104 

| DMSM0D116S LOADER TABLE OVERFLOW RC=104 
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MACLIB 



Use the MACLIB command to create and modify macro libraries. A aacro 
library consists of aeabers (aacro definitions) and a dictionary which 
contains the naie of the ■aero (neaber name) , its size, and its location 
relative to the beginning of the library. The BACLlB command d hecks 
only the aacro definitions of MACRO and BEND statements for errors* The 
foraat of the HACLIB coaaand is: 




GE1 

ADD libnaae fn1 [fn2...] 

BEP 

DEL libnaae aeabernaael [aeabernaae2.. 

COUP libnaae 

HAP libnaae [ (options. ..[)] ] 

options; 

r i 
|TBBB | 
IDISK | 
iPRIHTI 

L J 



•] 



where; 

GEH 

ADD 

BEP 

DEL 

COBP 

HAP 

libnaae 

fn1 [fn2... ] 



generates a CBS aacro library. 

adds members to an existing aacro library. 

replaces existing aeabers in a aacro library. 

deletes aeabers froa a aacro library. 

compacts a aacro library. 

lists certain information about the aeabers in a aacro 
library. Available information includes aeaber name, 
size, and location relative to the beginning of the 
library. 

is the filenane of a aacro library. If the file already 
exists, it aust have a filetype of HACLIB; if it is being 
created, it is given a filetype of BACLIB. 

are the naaes of the aacro definition files to be used. 
A aacro definition file aust reside on a CHS disk and Its 
filetype aust be either HACBO or COPT. Each file aay 
contain one or aore aacros and aust contain fixed-length, 
80-character records. 

In a BACBO file, the aacro name is taken from a prototype 
statement within the macro. 

If the filetype is COPT and the file contains more than 
one macro, each macro must be preceded by a control 
statement of the following format: 
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*COPY membername 

The naie on the control statement is the name of the 
macro when it is placed in the macro library. If there 
is only one macro in the COPY file and it is not preceded 
by a COPT control statement, its name (in the macro 
library) is the same as fn. If there are several macro 
definitions in a COPY file and the first one is not 
preceded by a COPY control statement the entire file is 
treated as one macro. 



membernamel. . . is the name of a macro vhich exists in a macro library. 



MAP Options 



TERM is the device to contain the 
DISK function. Valid device names 
PRINT (virtual spooled printer) , a 
device is specified, DISK is 
the only options allowed in 
first word after the left p 
the DISK option is specified, 
to a file named ' libname HAP 
name previously existed it is 



output generated by the HAP 

are DISK (disk file) , PRINT 

nd TERH (terminal) . If no 

assumed. Since these are 

the HACLIB command, only the 

arenthesis is examined. If 

the information is written 

A1 ( . If a file with that 

replaced by the new file. 



The following 
command. 



paragraphs describe each of the functions of the HACLIB 



GEN Function 



The GEN (generate) function creates a new CHS macro library with the 
filename and filetype you specify on the HACLIB command. If a macro 
library with the same filename already exists, it is erased and replaced 
by the new macro library. The new file is created from input files 
specified by fni fn2 ... For example: 

HACLIB GEN OSHAC ACCESS TIHE PUT REGBQU 

Creates a new macro library with the file identification OSHAC HACLIB 
from macros existing in the files with the file identifiers: 

ACCESS (HACRO), TIHE ( HACRO LPUT j HACRO \ and REGEQD f HACRO \ 
\ COPY J (COPY J \C0PY J (COPY J 

If a file named OSHAC HACLIB already exists, that file is erased. 



Assume that the files ACCESS HACRO, TIHE COPY, PDT HACRO, and REGEQO 
COPY exist and contain macros in the following form. 



ACCESS HACRO 
GET 
POT 



TIHE COPY 

♦COPY TTIHER 

TTIHBR 
♦COPY STIHER 

STIHER 



PUT HACRO 
PUT 



REGEQU COPY 
XREG 
YREG 
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The resulting file OSHAC MACLIB contains the following members: 

GET 

POT 

TTIHER 

STIHER 

POT 

BEGEQO 

Note: The POT Macro, which appears twice in the input to the command, 
also appears twice in the output. The MACLIB command does not check for 
duplicate macro names. If, at a later time, the POT macro is reguested 
from OSHAC MACLIB, the first POT macro encountered in the dictionary is 
used. 



ADD Function 



The ADD function appends the members described by the macro definition 
files (fn1 fn2...) to an existing macro library. 

MACLIB ADD OSHAC DCB 

Assume that OSHAC HACLIB was created by the example in the 
explanation of the GEH function and the file DCB COPY exists as 
follows. 

*COPI DCB 

DCB macro definition 
♦COPY DCBD 

DCBD macro definition 

The resulting OSHAC HACLIB contains the following members: 

GET 

POT 

TTIMER 

STIHER 

POT 

BEGEQO 

DCB 

DCBD 



REP Function 



REP (replace) is effectively a delete function followed by an ADD 
function. REP deletes the dictionary entry for the macro definition in 
the files specified by fn1 fn2 ... It then appends the new macro 
definitions to the macro library and creates new dictionary entries. 
For example, assume that a macro library HYHAC HACLIB contains the 
members A, B, and C, and that the following command is entered: 

HACLIB REP HYHAC A C 

The files represented by file identifiers A HACRO and C MACRO each have 
one macro definition. After execution of the command, HYHAC HACLIB 
contains members with the same names as before, but the contents of A 
and C are different. 
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DEL Function 

The DEL (delete) function removes the specified macro name from the 

macro Ixbrary uxctxonary 3&u compresses tu€ uxctxcnary so there are no 

unused entries. The macro definition still occupies space in the 
library, but since no dictionary entry exists it cannot be accessed or 

retrieved. If you attempt to delete a macro for which two macro 

definitions exist in the macro library, only the first one encountered 
is deleted. For example: 

HACLIB DEL OSHAC GET PUT TTIHER DCB 

| deletes macro names GET, POT, TTIMER, and DCB from the dictionary of the 
| macro library named OSHAC HACLIB. Assume that OSHAC exists as in the 

ADD function example. After the above command, OSHAC contains the 

following members: 

STIHEB 
POT 

REGEQO 
DCBD 



COHP Function 

Execution of a HACLIB command with the DEL or REP functions can result 
in unused space within a macro library. The COHP (compress) function is 
used to compress a macro library (that is, remove any macros for which 
there is no dictionary entry) . This function uses a temporary data set 
named HACLIB CHS0T1. For example, the command: 

HACLIB COHP MYHAC 



Compresses the library HTHAC HACLIB. 



HAP Function 

The HAP function creates a list containing the name of each macro in the 
dictionary, the size of the macro, and its position within the macro 
library. You can specify the device to which the list is to be 
written. Acceptable devices are: 

DISK the list is placed in a file with the file identification 
•libname HAP A1«. 

PRINT the list is spooled to the printer. 

TERH the list is displayed at the terminal. 
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I Response 



| When the HAP operand is specified on the MACLIB coaaand, the response 
| is: 

| aeabernaae size location 



Ot her Messages and Return Codes 

DHSLBM001E HO FILENAME SPECIFIED RC=24 

DMSLBM002E FILE «fn ft 1 MOT FOUND RC=28 

DMSLBM002H FILE • f n ft fa» NOT FOUND RC=4 

DMSLBM003E INVALID OPTION •option* RC=24 

DMSLBM013S MEMBER »naae» HOT FOUND IH LIBRARY • f n ft fa 1 RC=4 

DMSLBM014E IHVALID FUNCTION 'function* RC=24 

DMSLBM037E DISK »aode» IS READ/ONLY RC=36 

DMSLBM046E HO LIBRARY HAME SPECIFIED RC=24 

DMSLBM047E NO FUNCTION SPECIFIED RC=24 

DMSLBM056E FILE • f n ft fa» CONTAIHS IHVALID RECORD FORMATS RC=32 

DMSLBM070E IHVALID PARAMETER •paraa* RC=24 

DMSLBM104S ERROR «nn« READIHG FILE «fn ft fa" FROM DISK RC=100 

DMSLBM105S ERROR »nn» HRITIHG FILE • f n ft fa« OH DISK RC=100 

DMSLBM109S VIRTUAL STORAGE CAPACITY EXCEEDED RC=104 

DHSLBH157S MACLIB LIMIT BXCEEDED[ , LAST MEMBER HAME ADDED HAS 

• aeabernaae ' ] RC=88 
DMSLBM167S PREVIOUS MACLIB FUNCTION NOT FINISHED RC=88 
DMSLBM213N LIBRARY «fn ft fa« NOT CREATED RC=4 
DMSLBM907T I/O ERROR ON FILE «fn ft fa« RC=256 
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MODMAP 

Use the MODMAP command to display the load map associated with the 
specified MODULE file. Two types of modules contain no load map and 
therefore produce an error message when they are specified in a HODHAP 
command. Ihey are (1) CHS transient area modules and (2) HODULE files 
created with the GEHHOD command using the NOHAP option. The format of 
the HODHAP command is: 



i — - - -^■-=^^^- - , 

| HODmap | fn I 



w h er e : 

fn is the filename of the HODULE file whose load map is to be 

displayed. The filetype of the file must be HODULE. 



Responses 

The load map associated with the file is displayed at the terminal 

Other Messages and Return Codes 

DHSHDP001E HO FILEHAHE SPECIFIED RC=24 
DHSHDP002E FILE • f n ft 1 HOT FOUHD RC=28 
DHSHDP018E HO LOAD HAP AVAILABLE RC=40 
DHSHDP070E IHVALID PARAHETER »param» RC=24 



Section 7: Format and Usage Rules for CHS Commands 175 



MOVEFILE 



MOVEFILE 



Use the MOVEFILE command to move data from any device supported by 
VM/370 to any other device supported by VM/370. The command accepts two 
ddnames as arguments. The FILEDEF command must have specified devices 
or disk files for these ddnames. The command moves data records from 
the device, or file, specified by the first ddname to the device, or 
file, specified by the second ddname. The format of the MOVEFILE 
command is: 



r _. _ 








-1 




r 


r n n 


option: 






linputddname 


| output ddname | | 






| MOVEfile 


1 1 

III! MOVE 


1 1 1 
IQUTMOVE | | 


[ (PDS[)]] 




i „,_ , _. 


L 


L J J 







where: 
inputddname 



is the ddname representing the input file definition. If 
ddname is not specified, the default input filename, 
INMOVE, is used. 



outputddname 



is the ddname representing 
If ddname is not specified, 
OOTMOVE, is used. 



the output file definition, 
the default output filename, 



0£t ion : 
PDS 



moves all of the members of the CHS MACLIB or TXTLIB or 
of an OS partitioned data set into separate CMS files, 
each with a filename egual to the member name and a 
filetype egual to the filetype of the output file 
definition (FILEDEF) . 



Note: Normally, the FILEDEF command is used to establish device 
characteristics for the ddname specified with the command. If the 
FILEDEF command was not issued, the OS macro simulation routines supply 
default characteristics. For example, if the ddname is X a default 
FILEDEF X DISK FILE X A1 command is executed. 



Default Device Attributes 



If a record format (BECFM) , blocksize (BLOCK) , and logical record length 
(LRECL) are specified on the FILEDEF command, these values are used in 
the data control block (DCB) defining the characteristics of the move 
operation. If the FILEDEF was issued without the record format 
specification, that specification is taken from the default list shown 
in Figure 28. If the blocksize was not specified, the default blocksize 
is used. If the logical record length was not specified, the default 
logical record length is determined as follows: if the record format is 
F or 0, the logical record length eguals the blocksize; if the record 
format is V, the logical record length eguals the blocksize minus 4. 
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r ■ - - 




Input 


ddname 




| Output ddname 


| Device 




RECFM 


I Blocksize 


| RECFM 


Blocksize 


j Card Reader 




F 


| 80 




! NA 2 


NA 2 


| Card Punch 




HA 2 


| NA 2 




I 

I F 


80 


| Printer 




HA 2 


| NA 2 




I 


132 


| Terminal 







| 130 




I 


130 


| Tape* 







| 3600 




I 

| RECFM Of 

| input ddname 


Blocksize of 
input ddname 


i Disk file 


RECFM Of 

file 


IBlocksize 
S file 


of 


I 

| RECFM of 

! input ddname 


Blocksize of 
input ddname 


I Dummy 




HA 2 


| NA 2 




| RECFM of 

I input ddname 


Blocksize of 
input ddname 


| *If the default record format and blocksize are used in a 

| tape-to— tape move operation and an input record is greater than 3600 

I bytes, it is truncated to 3600 bytes on the output tape. 

| 2 Not applicable. 



Figure 28. Default Device Attributes for MOVEFILE Command 



Example 



The existing file whose file definition ddname is NEWMAST is moved to 
the file whose file definition ddname is OLDHAST. 

MOVEFILE NEWMAST OLDMAST 

The following seguence of CMS commands move an OS STOW macro file 
from an OS partitioned data set SYS 1. MACLIB or a CMS file SYS1 MACLIB to 
the CMS file STOW MACRO. 

ACCESS 195 B/A 

FILEDEF TEST1 DISK SYS1 MACLIB B1 (MEMBER STOW) 

FILEDEF MACRO DISK STOW MACRO 

MOVEFILE TEST1 MACRO 

The following seguence of CMS commands moves all the members of an OS 
partitioned data set SYS1. MACLIB or a CMS file SYS1 MACLIB into separate 
CMS files each with a filename egual to its member name and a filetype 
of MACRO. 

ACCESS 195 B 

FILEDEF TEST2 DISK SYS1 MACLIB B1 

FILEDEF MACRO DISK 

MOVEFILE TEST2 MACRO (PDS) 

| For more examples of how to move OS data sets and DOS files to CHS 
files using MOVEFILE, see "Using OS Programs and Macros under CMS" in 
Section 4. 



Section 7: Format and Osage Rules for CMS Commands 177 



MOVEFILE 
Res£onses 

DHSHVE225I FDS HEHBBB 'membername' MOVED 

The specified member of an OS partitioned data set was moved 
successfully to a CHS file. 

DHSMVE226I END OF PDS HOVE 

The last member of the partitioned data set was aoved successfully 
to a CMS file. 

DMSHVE706I TEBH IHPUT — TYPE HULL LIHE FOR EHD OF DATA 

The input ddnaae in the HOVEFILE command refers to a terminal. 
This message requests the input data; a null line terminates 
input. 

DHSHVE708I DISK FILE 'FILE ddname A1' ASSUHED FOB DDNAHE 'ddname' 

No FILEDEF command was issued for a ddname specified on the 
HOVEFILE command. As a result the HOVEFILE issues a FILEDEF for 
that ddname. 

If the input ddname is undefined, the file must exist. The block 
size and record format are taken from this file. 

If the output ddname is undefined, the disk file is created on the 
A-disk with the same characteristics as those of the input file. 



Other Hessaqes and Return Codes 

DHSHVE002E FILE 'fn ft fm' NOT FOUND BC=28 

DHSHVE003E INVALID OPTION 'option 1 RC=2U 

DHSHVE037E OOTPDT DISK 'mode' IS READ/ONLY RC=36 

DHSHVE041E INPDT AND OUTPUT FILES ABE THE SAHE BC=40 

DHSHVE048E INVALID HODE 'mode' RC=24 

DHSHVE070E INVALID PABAHETEB 'param* BC=2U 

DHSHVE073E UNABLE TO OPEN FILE ddname BC=28 

DHSHVE075E DEVICE 'device name' ILLEGAL FOB { INPUT |OUTPUT} BC=40 

DHSHVE086E INVALID DDNAHE 'ddname* BC=24 

DHSHVE127S UNSUPPOBTED DEVICE FOB ddname RC=100 

DHSHVE128S I/O ERROB ON INPUT AFTEB BEADING nnnn BECOBDS : INPUT EBBOB 

code ON ddname BC=tOO 
DHSHVE129S I/O EBBOB ON OUTPUT WRITING BECOBD NUHBEB nnnn: OUTPUT EBBOB 

code ON ddname BC=100 
DHSHVE130S BLOCKSIZE ON V FOBHAT FILE ddname IS LESS THAN 8 BC=88 
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PRINT 



Use the PRINT command to print a CMS file on the spooled virtual 1403 or 
3211 printer. The file may contain carriage control characters and may 
have either fixed- or variable-length records, but no record may exceed 
132 characters for a 1403 or 150 characters for a 3211. There are two 
exceptions to this: 

1. If the CC option is in effect, the record length can be one 
character longer (133 or 151) to allow for the carriage control 
character. 

2. If the HEX option is in effect, a record of any length can be 
printed, up to the CMS file system maximum of 65,535 bytes. 

Note: An option may not be in effect, even though it is specified. See 
the discussion of the PRINT options for information on overriding 
options. 

The format of the PRINT command is: 



PRint 



r t 

fn ft |fm| [ (options. ..[) ]] 

I* I 

L J 

r n 

options: | CC | 

|N0CC| [UPCASE] 

L J 



r r t i 

|LInecoun | nn | | 

I 1 55 | | 

L L J J 



MEMBER 



( membername J 



I [HEX] 



w her e : 
fn 

ft 

fm 



is the filename of the file to be printed. This field 
must be specified. 

is the filetype of the file to be printed. This field 
must be specified. 

is the filemode of the file to be printed. If this field 
is specified as an asterisk (*) , the standard order of 
search is followed and the first file encountered, with 
the given filename and filetype, is printed. If fm is 
not specified, the primary disk and its extensions are 
searched. 



Options 



CC 



interprets the first character of each record as a 
carriage control character. If the filetype is 
LISTING, the CC option is assumed. If CC is in 
effect, the PRINT command does not perform page ejects 
or count the number of lines per page; these functions 
are controlled by the carriage control characters in 
the file. The LINECOUN option has no effect if CC is 
in effect. 
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PRIHT 

NCCC does not interpret the first character of each record 

as a carriage control character. In this case, the 
PRINT command performs the necessary carriage control 
to eject a new page and print a heading after the 
number of lines specified by LINECO0H are printed. If 
NOCC is specified, it is in effect even if CC was 
specified previously or if the filetype is LISTING. 

UPCASE translates the lowercase letters in the file to 
UP uppercase for printing. 

MEMBER ( * ) prints the members of macro or text libraries. This 
MEM \ name/ option may be specified if the file is a simulated 
partitioned data set (filetype MACLIB or TXTLIB) . If 
* is entered, all individual members of that library 
are printed. If a membername is specified, only that 
member is printed. 

HEX prints the file in graphic hexadecimal format. If HEX 

is specified, the options CC and OPCASE are not in 

effect, even if specified, and even if the filetype is 
LISTING. 

r n 

LINECOUN |nn| allows you to set the number of lines to be printed 

| 55 | on each page, nn can be any decimal number from 

L J through 99 and has a default value of 55. If nn is 

set to zero, the effect is that of an infinite line 

count and page ejection does not occur. This option 

has no effect if the CC option is also specified. 

Examples 

PRINT MYLIB MACLIB (MEMBER GET) 

Spools the contents of the member GET in file MYLIB MACLIB to the 
printer. The first character of each record in the file is not used for 
carriage control. 

PRINT OLDMAST NAME (CC) 

Spools the contents of the file OLDMAST NAME to the printer and uses the 
first character of each record in the file for carriage control. 

Responses 

None. 

The READY message indicates the command completed without error 
(that is, the file is written to the spooled printer) . The file is 
now under the control of CP spooling functions. 

Oih§I H§§§aa§§ §£§ !§tur_n Codes 

DMSPRT002E FILE ■ f n ft fm' NOT FOUND RC=28 

DMSPRT003E INVALID OPTION 'option' RC=24 

DMSPRT008E DEVICE 'cuu' {INVALID OR NONEXISTENT | UNSUPPORTED DEVICE TYPE} 

RC = 36 
DMSPRT013E MEMBER 'name' NOT FOUND IN LIBRARY RC=32 
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PRINT 



DMSPRT029E INVALID PARAMETER 'param' IN THE OPTION 'option' FIELD 

DMSPRT033E FILE »fn ft fm' IS NOT A LIBRARY RC=32 

DMSPRT039E NO ENTRIES IN LIBRARY 'fn ft f m • RC=32 

DMSPRT044E RECORD LENGTH EXCEEDS ALLOWABLE MAXIMUM RC=32 

| DMSPRT048E INVALID MODE 'fm' RC=24 

DMSPRT054E INCOMPLETE FILEID SPECIFIED RC = 24 

DMSPRT062E INVALID * IN FILEID RC=20 

| DMSPRT070E INVALID PARAMETER 'parm' RC=24 

DMSPRT104S ERROR «nn' READING FILE »fn ft f m ' FROM DISK RC=100 

DMSPRT123S ERROR PRINTING FILE ■ f n ft fm' RC= 100 



RC=2U 
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PUNCH 



PUNCH 



Use the PUNCH command to spool a specified CMS disk file to the punch. 
PUNCH accepts fixed- or variable— length records as long as no record 
exceeds 3G characters. Records with less than 80 characters are padded 
with blanks on the right. Records longer than 80 characters are 
rejected. The format of the PUNCH command is: 



PUnch 



fn ft |fm| 
I* I 

L J 



[ (options. ..[) ]] options: 



I HEADER | 
|H0HEADER| 

L J 



MEMBER j* 



membername j| 

j 



L. 



where: 
fn 

ft 

fm 



is the filename of the file to be punched. This field must 
be specified . 

is the filetype of the file to be punched. This file must 
be specified. 

is the filemode of the file to be punched. If this field is 
specified as an asterisk (*) , the standard order of search 
is followed and the first acceptable file encountered is 
punched. If fm is not specified, the primary disk and its 
extensions are searched. 



Options 



NOHEADER 
NOH 



inserts a control card in the punched output preceding 
the specified file. This control card identifies the file 
for a subsequent BEADCARD command to restore the file to 
a disk. If the filetype is TXTLIB and the MEMBER 
membername option is specified, the header card contains 
TEXT as the filetype. If the filetype is MACLIB and the 
MEMBER membername option is specified, the header 
contains MEMBER as the filetype. A macro library member 
originates from a file with a filetype of either MACRO or 
COPY. The control card format is shown in Figure 29. 

does not insert a header control card in the punched 
deck. 



MEMBER 
HEM 



membername j 

punches library members. If the filetype is MACLIB or 
TXTLIB, this option are specified. If * is entered, all 
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PUNCH 



individual members of that macro or text library are 
punched. If membername is specified, only that member is 
punched. 



| Column 


Number of 
Characters 


Contents 


Meaning 


| 1 


1 




> 


Identifies card as a control card. 


I 2-5 


4 




READ 


Identifies card as a READ control card. 


| 6-7 


2 




blank 




| 8-15 


8 




f name 


Filename of the file punched. 


|16 


1 




blank 




| 17-24 


8 




ftype 


Filetype of the file punched. 


|25 


1 




blank 




| 26-27 


2 




fmode 


Filemode of the file punched. 


| 28 


1 




blank 




| 29-34 


6 




volid 


Label of the disk from which the file was 
read. 


| 35 


1 




blank 




i 36-43 


8 




mm/dd/yy 


The date that the file was last written. 


| 44-45 


2 




blank 




| 46-50 


5 




hh:mm 


The time of day that the file was written 
to disk. 


151-80 


30 




blank 





Figure 29. Header Card Format 



Example 



PUNCH NERHAST TRANS (HOH) 

Spools the file NENHAST TRANS to the punch. No header card is punched 
preceding the output deck. 



Responses 



None. 



If the command completes without error (the file was successfully 
spooled) , the READY message appears. The file is now under control 
of CP spooling functions. 
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Pl-feer Messages and Return Codes 

DMSPUN002E FILE • f n ft fm» NOT FOOND RC=28 

DMSPUN003E INVALID OPTION •option 1 EC=24 

DMSPUN008E DEVICE »CUU« {INVALID OR NONEXISTENT (UNSUPPORTED DEVICE TYPE} 

RC=36 
DMSPUN013E MEMBER 'naie' NOT FOUND IN LIBRARY RC=32 
DMSPUN033E FILE «fn ft fm» IS NOT A LIBRARY RC=32 
DMSPUN039E NO ENTRIES IN LIBRARY • f n ft fm« RC=32 
DMSPUN044E RECORD LENGTH EXCEEDS ALLOWABLE MAXIMUM RC=32 
DMSPUN054E INCOMPLETE FILEID SPECIFIED RC=24 
DMSPUN062E INVALID * IN FILEID RC=20 

DMSPUN10US ERROR »nn« READING FILE • f n ft fm» FROM DISK RC=100 
DMSPUN118S ERROR PUNCHING FILE • f n ft fl« RC=100 
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QUERY 



QUERY 



Use the QUERY command to gather certain information about the CHS 
virtual machine environment. Information vhich may be obtained 
includes: 

• The state of any of the virtual machine characteristics which are 
controlled by the CHS SET command. 

• File definitions (set with the FILEDEF command) which are in effect. 

• The status of the disks attached to your virtual machine. 
The format of the QUERY command is: 




BLIP 

RDYHSG 

LDRTBLS 

RELPAGE 

IHPCP 

IHPEX 

ABBREV 

REDTYPE 

PROTECT 

IHPUT 

OUTPUT 

SEARCH 



DISK 



{ "; de } 



(SYSTEH 

synonyh < user 
(all 

FILEDEF 
HACLIB 
TXTLIB 
LIBRARY 




Options for SET Command Functions: 
BLIP displays the BLIP character (s) . 
Response: BLIP = /xxxxxxxx 



RDYHSG 



i xxxxxxxx \ 

I OFF J 



displays the RDYHSG format. 

Response: RDYHSG = f LHSG \ 

\ SHSG J 

where: 

LHSG is the standard CHS READY message: 

R; T = 0.12/0.33 17:06:20 

SHSG is the shortened CHS READY message: 

R; 
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IMPEX 
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QUERY 



LDBTBLS displays the number of loader tables. 
Response: LDBTBLS = nn 



RELPAGE indicates whether pages of storage are to be released or 
retained after certain commands complete execution. 



Response: RELPAGE = 



where: 



|0N ) 
(OFF J 



OH releases pages. 
OFF retains pages. 

displays the status of implied CP command indicator. 

Response: IMPCP = (ON ) 
I OFF J 

where : 

ON passes commands not recognized by CMS to CP. 
OFF flags commands not recognized by CMS. 

displays status of implied EXEC indicator. 

Response: IMPEX = ( ON \ 
(OFF) 

where : 

ON indicates that EXEC files can be executed by entering 

the filename of the file. 
OFF indicates that the EXEC command must be explicitly 

entered to execute EXEC files. 



ABBREV displays the status of the minimum truncation indicator. 

Response: ABBREV = ( ON ) 

(OFF J 

where: 

ON accepts minimum truncations for CMS commands. 
OFF does not accept minimum truncations. 



REDTYPE displays the status of the REDTYPE indicator. 

Response: REDTYPE = j ON ) 

(OFF/ 

where: 

ON types CMS error messages in red, for certain terminals 
equipped with the appropriate terminal feature and a 
two-color ribbon. Supported terminals are documented in 
the VM/370: Terminal User^s Guide. 



OFF 



does not type CMS error messages in red. 



Section 7: Format and Usage Rules for CMS Commands 185 



QUERY 



PROTECT 



OUTPUT 



displays the status of CMS nucleus protection. 
Jesponse: PROTECT = 



(OFF/ 



where 



ON means CMS nucleus protection is in effect. 
OFF means CMS nucleus protection is not in effect. 



INPUT displays the contents of your input translate table if one is 
specified. 



Response: INPUT a1 xx1 



an xxn 



If you do not have an input translate table in effect, the 
response is 

NO USER DEFINED INPUT TRANSLATE TABLE IN USE 



displays the contents of your output translate table if you 
have specified one. 



Response: OUTPUT xx1 a1 



xxn an 



If you do not have an output translate table defined, the 
response is 

NO USER DEFINED OUTPUT TRANSLATE TABLE IN USE 



Options for CMS Disk Status Functions: 



SEARCH displays the search order of all CMS disks currently 
accessible. 

Response: volid vaddr mode ( R/0 ) 

1R/W/ 



DISK mode displays the status of the single disk represented by 'mode', 

Response: mode (vaddr) : nn FILES, nnnn REC IN USE, nnnn LEFT 
(OF nnnn) , nn% FULL (n CYL) , type i R/0 ) 

IH/W/ 

If the disk is an OS-formatted disk, the response is: 

mode (vaddr): (n CYL), R/O-OS 
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If the disk with the specified mode is not accessed, the 
response is 

DISK •■Ode 1 NOT ACCESSED 

DISK * displays the status of all CMS disks. 

Response: saie as for QUERY DISK mode; one line is displayed 
for each accessed disk. 



Other Functions: 



SYNONYM SYSTEM 

displays the CMS system synonyms in effect. 

Response: System Shortest 

Command Form 

command minimum truncation 



If no system synonyms are in effect, the following message is 
displayed at the terminal: 

NO SYSTEM SYNONYMS IN EFFECT 



SYNONYM USER 

displays user synonyms in effect. 

Response: System User Shortest 

Command Syn ony m Form (if _anyl 

command synonym minimum truncation 



If no user synonyms are in effect, the following message is 
displayed at the terminal: 

HC USER SYNONYMS IN EFFECT 



SYNONYM ALL 

displays all synonyms in effect. 

Response: Same as SYNONYM SYSTEM and SYNONYM USER. 

FILEDEF displays all file definitions in effect. 

Response: ddname device [fn [ft]] 

If there are no user file definitions in effect, the following 
message is displayed at the terminal: 

NO USER DEFINED FILEDEF* S IN EFFECT 
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HACLIB displays the naies of all files with a filetype of HACLIB 
which are to be searched for aacro definitions. 



Response: HACLIB - libname... 

If no macro libraries are 
definitions, the response is: 

HACLIB = HOHE 



to be searched 



for aacro 



TXTLIB displays the naaes of all files with a filetype of TXTLIB 
which are to be searched for unresolved references. 

Response: TXTLIB = lib name... 

If no TXTLIBs are to be searched for unresolved references, 
the following message is displayed at the terminal: 

TXTLIB = HOHE 



LIBRARY displays the name of all macro and text library (files with 
filetypes HACLIB and TXTLIB) which are to be searched. 



Response: HACLIB = ( libname, 

) NONE 



I 11 

I NO 



TXTLIB = ( libname.. 
HOHE 






JEE2E Messages and Return Codes 



DHSQRY005E NO 'option* SPECIFIED RC=24 

DHSQRY014E IHVALID FDHCTIOH 'function* RC=24 

DHSQRY026E INVALID PARAHETER *param* FOR 'function* FDHCTIOH RC=24 

DHSQRY047E HO FDHCTIOH SPECIFIED RC=24 

DHSQRY070E INVALID PARAHETER *param* RC=24 
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READCARD 

Use the READCARD command to read data records from the virtual card 
reader (spool input device) and to create files on disk containing the 
data records. The data records must be fixed length and normally 
contain 80 characters, although they may contain up to 151 characters. 
Records less than 80 characters long cannot be read. If a file exists 
on disk with the same identifiers as the one to be created, it is 
erased. 

Any number of files may be entered through the card reader, each 
immediately preceded by a READ control card specifying the filename, 
filetype, and optionally the filemode. The READ control card is shown 
in Figure 30. The header card supplied when HEADER is specified with 
the CHS PUNCH command is a valid READ control card. 

All files that are logically grouped together must have the same 
record length. The READ control cards are displayed at the terminal as 
they are encountered, and interpreted just as if filename and filetype 
had been entered from the terminal. Each READ control card ends the 
preceding file, and the reader end-of-file indication ends the last 
file. 

lour files must be spooled to the virtual reader before a READCARD 
command can be issued. You can send your real card deck to your virtual 
card reader using the CP ID card in front of your real card deck. This 
card takes the form: 



r t 



(ID ) userid |CLASS c| NAME / f n f t \ 
( DSERID / ICLASS A| | dsname J 



w h er e : 

ID is a keyword that must begin in column one. 

USERID 

userid is the user's identification (userid) , limited to eight 
characters. 

CLASS c is the optional class field. If CLASS is not specified, 
class A is the default. 

NAME I fn ft 1 is the name field. If the first form is specified, the 

\ dsname J filename and filetype are each limited to eight 

characters. The filename and filetype must be separated 

by a blank. If the second form is used, the dsname field 

is limited to 24 characters. 

Note: Only the CLASS n operand is optional. All fields must be 
separated by at least one blank. The keyword ID or USERID must start in 
column one. 

You need not be logged on at the time the decks are transferred to 
your virtual reader. If more than one file is spooled to the virtual 
reader, more than one READCARD command must be issued to process all the 
logical files. If SPOOL RDR CONT is issued, all the logical files in 
the virtual reader are treated as a single file. Again, the files that 
are treated as one must all have the same record length. The format of 
the READCARD command is: 
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BEADCABD 



i — 

BEADcard | / r n 

fn ft | fm | 

I i I 

L J 

r r m 
* I * I fi II 

I I A || 

L L JJ 



where ; 

fn is the filename of the file to be read. An asterisk may be 
coded in this field. 

ft is the filetype of the file to be read. An asterisk nay be 
coded in this field if fn was coded as an asterisk. 

fa is the filemode of the file to be read. If this field is 
omitted or specified as an asterisk (*) , A is assumed. 
Whenever a mode number is specified on the command line, it is 
used. Otherwise, the mode number on the BEAD control card is 
used to create the disk file. 



Fo rms of the READCABD Operands 

BEADCABD HTFILE ASSEMBLE 

If filename and filetype are specified with the BEADCABD command, only 
one file is read. The BEAD control cards are ignored. 

BEADCABD * 

If the file identification is to be entered in the card stream, a single 
asterisk must be specified with the BEADCABD command. If this form of 
the command is specified, and the first card in the input stream is not 
a valid BEAD control card, a file named BEADCABD CHSDT1 A1 is set up to 
contain all data read until a valid BEAD control card is encountered. 
If fn ft fm was specified, the file is written on the specified disk 
with a mode number matching the filemode number from the control card. 
If the filemode number is specified, that number is used. If filemode 
is omitted, A is assumed. 

BEADCABD * * 

Two asterisks accept the filename, filetype, and filemode number from 
the BEAD control card, but use a filemode letter of A. 

BEADCABD * * B1 

Two asterisks with a mode specified accept the filename and filetype 
identifiers from the BEAD control card, but use the filemode specified. 

Whatever is specified on the BEADCABD command line is used. Whatever 
is not specified is taken from the BEAD control card, except the 
filemode letter, which defaults to A. If there is no BEAD control card, 
a BEAD control card 

:BEAD BEADCABD CHSUT1 A1 

is assumed. 
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BEADCABD 



r _ 


Number 


of 








— i 


| Column 


Characters 


| Contents 


I Meaning 






! 1 


! 1 




; : 


! Identifies card 


as a control card* 




I 2-5 


i 4 




I BEAD 


[identifies card 


as a BEAD control card. 




| 6-7 


2 




j blank 








| 8-15 


8 




|£n 


Filename of the 


file. 




|16 


1 




I blank 








| 17-24 


8 




|ft 


Filetype of the 


file. 




|25 


1 




| blank 








1 26-27 


2 




I fa 


IFilemode of the 


file. 




| 28-80 


53 




| anything 









Figure 30. Format of the BEAD Control Card 



Besponses 



After the command BEADCABD * is issued, control cards encountered in the 
input card stream are displayed at the terminal. 

DMSBDC701I NULL FILE 

The spooled card reader contains no records after the control 
card. 



DHSBDC702I BEAD CONTBOL CABD IS 
BEADCABD CMS0T1 A1 



MISSING. FOLLOWING ASSUMED: BEAD 



The first card in the deck is not a BEAD control card. Therefore, 
the file BEADCABD CMSUT1 A1 is created. 



DHSBDC738I BECOBD LENGTH IS *nnn* BYTES 

The records being read are not 80 bytes long; this message gives 
the length. 

| When a BEADCABD control card is encountered, the first 72 columns of a 
| card are displayed at the terminal. 



Other Messages and Beturn Codes 



DMSBDC008E DEVICE »cuu» {INVALID OB NONEXISTENT | UNSUPPOBTED DEVICE TYPE} 

BC=36 
DMSBDC042E NO FILEID SPECIFIED BC=24 
DMSBDC054E IHCOBBECT FILEID SPECIFIED BC=2*» 
DMSBDC062E INVALID * IN FILEID BC=20 

DMSBDC105S EBBOB »nn» WBITIHG FILE • f n ft fm» ON DISK BC=100 
DMSBDC124S EBBOB BEADING CABD FILE BC-100 
DMSBDC205R BEADEB EMPTY OB NOT BEADY BC-8 
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RELEASE 

Ose the RELEASE command to free an active disk when it is no longer 
needed. An ACCESS command must have been previously entered for the 
specified disk. The format of the RELEASE connand is: 

i ■ 1 

| RELease | | cuu ) | 

| | (mode J | 

i i 



where: 

cuu is the virtual device address of the disk that is to be 
released. 

| Note that 000 is not a valid address. 

■ode is the mode of the disk to be released. 

Note: If a disk is accessed more than once, the RELEASE cuu command 

releases all instances of cuu. The system disk cannot be released. 



Error Messages and Return Code s 



DMSARE017E INVALID DEVICE ADDRESS »cuu» RC=24 

DHSARE028E BO DEVICE SPECIFIED RC=24 

DMSARE048E INVALID MODE •mode 1 RC=24 

DBSARE069E DISK { 'mode 1 | »cuu» } NOT ACCESSED RC=36 

DMSARE070E INVALID PARAMETER 'param* RC=24 
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RENAME 



Use the RENAME coanand to change the file identification of one or nore 
files. The RENAME coanand nay not be used for a file which is located 
on a read-only disk. The fornat of the RENAME coanand is: 



Renane | fileidl fileid2 [ (options. ..[) ]] 

options; 



r n r t 

jTTPE i iSJPDIRT | 

INOTYPEI |NODPDIRT| 

I J L J 




fileid2 



is the file identification of the original file whose nane 
is to be changed. All conponents of the file (filenane, 
filetype, and filenode) nust be coded, either with a nane or 
an asterisk. If an asterisk is coded in any field, any file 
which satisfies the other qualifications is renaned. For 
exanple, if fileidl is coded as A * A1, all files on the A 
disk with a filenane of A are renaned. 

is the new file identification of the file. All conponents 
of the file (filenane, filetype, and filenode) nust be 
coded, with either a nane or an equal sign. If an equal 
sign is coded, the corresponding file identifier is 
unchanged. 



Options 



TYPE displays at the terninal the new identifiers 
T of all files renaned. The file identifiers are displayed 

only when an * is specified for one or nore of the file 

identifiers (fn, ft or fn) in fileidl. 

NOTYPE suppresses displaying at the terninal of the new file 
NOT identifiers of all files renaned. 

OPDIRT updates the Master File Directory upon completion of 
UP this conmand. 

NODPDIRT suppresses the updating of the Master File Directory 
NOUP upon conpletion of this connand. Normally, Master File 

Directories are updated at the conpletion of each CHS 

connand that affects disk files. 
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RENAME 



newfn nevft nevfa 

The new filename, filetype, and fileaode of each file altered is 
displayed only when the TYPE option is specified and an asterisk 
vas specified for at least one of the file identifiers (fn, ft or 
fa) of the original file. 

If fileid2 is the name of an existing file, an error Message is 
generated. 



Other £©§§3i3§§ §Sd Return Co des 

DMSRNM002E FILE »fn ft fa« NOT FOUND RC=28 

DHSRNH003E INVALID OPTION »option» RC=24 

DMSRNM019E IDENTICAL FILEIDS RC=24 

DMSRNM024E FILE • f n ft fn* ALREADY EXISTS RC=28 

DMSRNM030E FILE • f n ft fa« ALREADY ACTIVE RC=28 

DMSRNM037E DISK 'mode (cuu) « IS READ/ONLY RC=36 

DMSRNM051E INVALID NODE CHANGE RC=24 

DMSRNM054E INCOMPLETE FILEID SPECIFIED RC=21 

DMSRNM062E INVALID * IN OUTPUT FILEID RC=20 

I Note; You can invoke the RENAME command froi the terminal, from an EXEC 
| file, or as a function from a program. If RENAME is invoked as a 
| function or froa an EXEC file that has the 6C0NTR0L NOHSG option in 
| effect, the DMSRNH002E FILE fn ft fa NOT FOUND error aessage is not 
| issued. 
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RON 
RUN 

Use the RUM command to initiate an automated series of functions on a 
file. The RUN command can compile, load, and start execution of the 
specified file, depending upon the filetype. The acceptable filetypes 
are: EXEC, MODULE, TEXT, and those required by the language processors. 
The RUN command is an EXEC procedure: if it is executed from within an 
EXEC file, it must be preceded by the EXEC command name. The format of 
the RUN command is: 



i 1 

I RUN | fn [ft [fm]] [(args...)] ! 

i 1 



where : 

fn is the filename of the file to be manipulated. This field must 
be entered. 

ft is the filetype of the file to be manipulated. If filetype is 
not specified, a search is made for a file with the specified 
filename and the filetype of EXEC, MODULE, or TEXT (the search 
is performed in that order) . If the filetype of an input file 
for a language processor is specified, the language processor 
is invoked to compile the source statements and produce a TEXT 
file. Then, LOAD and START are called to initiate program 
execution. The filetype must be specified if filemode is 
specified. The valid filetypes and resulting action for this 
command are: 

liietype Action 

EXEC The EXEC processor is called to process the file. 

MODULE The LOADMOD command is issued to load the program 
into storage and the START command begins execution 
of the program at the entry point equal to fn. 

TEXT The LOAD command brings the file into storage in an 
executable format and the START command executes the 
program beginning at the entry point named by fn. 

FORTRAN The FORTRAN processor module that is called is 
FORTRAN, FORTGI, GOFORT, TESTFORT, or FORTHX, 
whichever is found first. 

FREEFORT The GOFORT module is called to process the file. 

COBOL The COBOL processor module that is called is COBOL 
or TESTCOB, whichever is found first. 

PLI The PLIOPT processor module is called to process 
PLIOPT the file. 

fm is the filemode of the file to be manipulated. If this field 

is specified, a filetype must be specified. If fm is not 

specified, the default search order is used to search your 
disks for the file. 
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args are one or more user arguments to te used during execution. 
If compiling or loadig is to be performed, it is assumed that 
the default options for those functions are in effect. You can 
specify up to 13 arguments in the SUN command, provided they 
fit on a single input line. These arguments are used during 
the operation of an EXEC file, or during execution of a MODULE 
or TEXT file. The arguments are set up as a string of 
doublevords, one argument per doublevord. The address of this 
string is passed to the specified file at execution time. 
Each argument is left- justified, and any argument more than 
eight characters long is truncated on the right. With an EXEC 
file, any arguments specified in the BUN command replace the 
corresponding Sn operands in the individual commands of the 
EXEC file. 

With a file whose filetype is other than EXEC, the arguments 
are placed in a string as described above. The address of the 
string is passed to the specified file at execution time. The 
end of the argument list is denoted by a X'FF' in the first 
byte of the argument field. 



?I£2£ Messages and Beturn Codes 



DMSBUN001E NO FILENAME SPECIFIED BC=24 
DMSBUN002E FILE 'fn ft fm» HOT FOUND BC=28 
DMSRUN032E INVALID FILETYPE 'ft 1 BC=24 

| DMSBUN0U8E INVALID MODE •fm' BC=24 

DMSRUN070E INVALID PABAMETEB »param» RC=24 

I DMSRUN999E NO ft PROCESSOR FOUND RC=28 
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SET 



Use the SET coanand to establish, turn off, or reset a particular 
function in your CMS virtual machine. Only one function may be 
specified per SET command. The format of the SET command is: 



SET 



function 
functions: 



r i 

jBLIf string[ (count) ]j 
| BLIP ON | 

| BLIP OFF | 

L J 



[LDBTBLS nn] 



r t 

lABBRBV OH | 
lABBREV OFF I 

L J 

r t 

| IB PC P ON | 
IIHPCP OFF | 

L J 



r t 

| EEL PAGE OH \ 
IRELPAGE OFF | 

L J 



r t 

| RED TYPE OH | 

IREDTYPE OFF | 

L J 

r t 

I PROTECT OH | 

| PROTECT OFF | 

L J 



r t 

IBDYHSG LHSGI 

IRDYMSG SHSG| 

L J 



r r t t 
IIHPOT | a xx| I 
I I xx yy| | 

L L J J 

[OUTPUT [xx a] ] 

r i 

| IMP EX OH | 
IIMPEX OFF | 

L J 

r i 

IAUTOREAD OH | 
IAUTOREAD OFF | 
i J 



L 



BLIP OH 



where: 

Functions 

BLIP string[ (count) ] defines the characters which are displayed at the 

terminal to indicate every two CPU seconds of real 
(or virtual) execution time. Up to eight 
characters can be defined, and if trailing blanks 
are desired, the count field must be used. OH and 
OFF must not be used as BLIP characters. 

sets the BLIP character string to its default, 
which is a string of nonprintable characters. OH 
is the default for typewriter devices. The default 
BLIP character provides no visual or audio— visual 
signal for the 3767 terminal. Thus, another 
character must be defined as the BLIP character for 
the 3767 if you want the BLIP function. 

turns off BLIP. OFF is the default for graphics 
devices. 

indicates that the standard CMS Ready message, 
including current and elapsed time, is used. The 
format of the standard Ready message is: 

R; T s s.mm/s.mm hh:mm:ss 

where the virtual CPU time. Real CPU time, and 
clock time are listed. 



BLIP OFF 
ROYMSG LHSG 



RDYHSG SMSG 



indicates that a shortened form of the CHS Ready 
message (R;) which does not include the time, is 
used. 
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LDRTBLS nn 



defines the number (nn) of pages of storage to be 
used for loader tables. By default, a virtual 
machine having up to 384K of addressable real 
storage has two pages of loader tables; a larger 
virtual machine has three pages. This nuaber can 
be changed with the SET LDRTBLS nn coaaand provided 
that: (1) nn is a deciaal nuaber less than 128, (2) 
the virtual aachine has enough storage available to 
allow nn pages to be used for loader tables, and 
(3) the system has not started using storage just 
below the LDRTBLS. If these three conditions are 
met, nn pages are set aside for loader tables. If 
you plan to change the nuaber of pages allocated 
for loader tables, you should do so as soon after 
IPL as possible. 



RELPAGE ON 



releases page frames of storage and sets thea to 
binary zeros after the following comaands complete 
execution: ASSEMBLE, COPYFILE, COMPARE, EDIT, 

MACLIB, SOBT, TXTLIB, UPDATE, and the Prograa 

Product language processors supported by VM/370. 

These processors are listed in the VM/370: 
Introduction. 



RELPAGE OFF 



does not release pages of storage after the 
commands listed in the previous paragraph complete 
execution. Use the SET RELPAGE OFF function when 
debugging or analyzing a problem so that the 
storage used is not released and can be examined. 



IHPUT a xx 



translates the specified character a to the 
specified hexadecimal code xx for characters 
entered from the terminal • 



IHPUT xx yy 



allows you to reset the hexadecimal code xx to the 
specified hexadecimal code yy in your translate 
table. 



Bote: If you issue SET INPUT and SET OUTPUT 
coaaands for the same characters, the SET OUTPUT 
command must be issued first. 



INPUT 



returns all 
translation. 



characters 



to 



their default 



OUTPUT xx a 



translates the specified hexadecimal representation 
xx to the specified character a for all xx 
characters displayed at the terminal. 



OUTPUT 
ABBREV ON 



returns all 
translation. 



characters to 



their default 



allows the system abbreviation or your own 
abbreviation (if one is available) to invoke a 
system command. The STNONTH command makes the 
system and user abbreviations available. 



ABBREV OFF 



invokes a command only when the full system command 
name or the full user synonym (if one is available) 
is entered. 



For a discussion of the relationship of the SET 
ABBREV and SYNONYM commands, refer to the SYNONYM 
command description. 
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SET 



I SI2TYPE OH 

i 

I 

I 

! 

REDTYPE OFF 
IHPEX ON 

IHPEX OFF 

IHPCP ON 

IHPCP OFF 
PROTECT ON 
PROTECT OFF 
AUTOREAD ON 

AOTOREAD OFF 



types CHS error messages in red for certain 
terminals equipped with the appropriate terminal 
feature and a two-color ribbon. Supported 
terminals are documented in the VM/370; Terminal 
User's Guide, 



suppresses red typing of error messages, 
treats EXEC files as commands; 



invoked when the 
entered. 



filename of 



an EXEC file 
the EXEC file 



is 
is 



does not consider EXEC files as commands. to 
execute an EXEC file, the EXEC command name must be 
issued. 

passes command names that CHS does not recognize to 
CP; that is, unknown commands are considered to be 
CP commands. 

generates an error message at the terminal if a 
command is not recognized by CHS. 

protects the CHS nucleus against writing within its 
storage area. 

does not protect the storage area containing the 
CHS nucleus. 

specifies that a console READ is to be issued 
immediately after command execution. ON is the 
default for non-display, non-buffered terminals. 

specifies that you do not want a console READ until 
you depress the Enter key or its equivalent. OFF 
is the default for display terminals because the 
display terminal does not lock, even when there is 
no READ active for it. 



U/l+A. t-f 






■ sots : It a user disconnects iioi one tjpe Oj. tmiioai ana reconnects on 
| to another type, the AUTOREAD status will remain unchanged. 



III9.E Jtessages and Return Codes 



DHSSET014E INVALID FUNCTION 'function 1 RC=24 

DHSSET026E INVALID PARAHETER 'param' FOR 'function' FUNCTION 

DMSSET031E LOADER TABLES CANNOT BE HODIFIED RC=40 

DMSSET047E NO FUNCTION SPECIFIED RC=24 

DHSSET061E NO TRANSLATION CHARACTER SPECIFIED RC=24 

DHSSET070E INVALID PARAHETER 'param' RC=24 



RC=24 
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SORT 

Use the SORT command to read fixed-length records from a CMS input file, 
arrange them in ascending EBCDIC order according to specified sort 
fields, and create a new file containing the sorted records. The input 
and output files must not have the same file identifiers, since SORT 
cannot write the sorted output back into the space occupied by the input 
file. If a file with the same name as the output file already exists, 
the old file is erased. The format of the SORT command is: 



i 1 

| SORT | fileidl fileid2 | 

i 1 



w her e : 

fileidl is the file identification (filename, filetype, filemode) of 
the file containing the records to be sorted. 

fileid2 is the file identification (filename, filetype, filemode) of 
the new output file to contain the sorted records. 

Entering Sort Control Fields: After the SORT command is entered, CMS 
responds with the following message on the terminal: 

DMSSRT604R ENTER SORT FIELDS: 

You should respond by entering one or more pairs of numbers of the form 
"xx yy" separated by one or more blanks. Each xx is the starting 
character position of a sort field within each input record and yy is 
the ending character position. The leftmost pair of numbers denotes the 
major sort field. The number of sort fields is limited to the number of 
fields you can enter on one line. The records can be sorted on up to a 
total of 253 positions. 

lll^ual Storage Requirements for sorting: The sorting operation takes 
place with two passes of the input file. Pass one creates an ordered 
pointer table in virtual storage. Pass two uses the pointer table to 
read the input file in a random manner and write the output file. 
Therefore, the size of storage and the size and number of sort fields 
are the limiting factors in determining the number of records that can 
be sorted at any one time. An estimate of the maximum number of records 
that can be sorted is: 

VMSIZE - 132K 
NR = 

14 + NC 

where: NR is the estimated maximum number of input records; NC is the 
total number of characters in the defined sort fields; VMSIZE is the 
storage size of the virtual machine; and 132K is the size of the 
resident CMS nucleus. For example, enter the command and respond to the 
prompting message: 

sort name address a1 sortedna address b1 

DMSSRT604R ENTER SORT FIELDS: 

1 10 25 28 

The records in the file NAME ADDRESS are sorted on positions 1-10 and 
25-28. The sorted output is written into the newly created file 
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SOBT 

SORTEDNA ADDRESS. If you have a 320K virtual machine, you can sort a 
maximum of 6875 records. 

VMSIZE-132K 320K-132K 188K 192,512 

NR = = = = = 6875 

14 + HC 14 + 14 28 28 



Responses 

DMSSRT604R ENTER SORT FIELDS: 

You are requested to enter SORT control fields. You should enter 
them in the form described in "Entering Sort Control Fields." 



Other Messages and Return Codes 



DMSSRT002E FILE • f m ft fm« NOT FOUND RC=28 

DMSSRT009E COLUMN "col 1 EXCEEDS RECORD LENGTH RC=24 

DMSSRT019E IDENTICAL FILEIDS RC=24 

DMSSRT034E FILE 'fn ft f m • IS NOT FIXED LENGTH RC=32 

DMSSBT037E DISK 'mode' IS READ/ONLY RC=36 

DMSSRT053E INVALID SORT FIELD DEFINED RC=24 

DMSSRT054E INCOMPLETE FILEID SPECIFIED RC=24 

DMSSRT062E INVALID * IN FILEID RC=20 

DMSSRT063E NO LIST ENTERED RC=40 

DMSSRT070E INVALID PARAMETER 'param 1 RC=24 

DBSSRT104S ERROR 'nn 1 READING FILE • f n ft fm« FROM DISK RC=100 

DMSSRT105S ERROR 'nn' WRITING FILE • f n ft f m • ON DISK RC=100 
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START 

Use the START command to begin execution of programs that were 
previously loaded, and to pass the address of a string of arguments to 
that program. The format of the START command is: 

i 1 

I I r -, I 

| START | | entry [args...] | | 

III* I I 

I I «■ J I 

i 1 

where : 

entry passes control to the control section name or entry point 
name at execution time. The operand, entry, may be a 
filename only if the filename is identical to a control 
section name or an entry point name. 

* passes control to the default entry point. The default 

entry point is either the address specified in the operand 
field of the first END control statement containing a 
non-blank operand field, or the beginning of the first file 
loaded if all END control statements in the TEXT files 
contains blank operand fields. The default entry point can 
be changed by specifying the RESET option on the INCLUDE 
command, when loading additional files. 

args... are arguments to be passed to the started program. If user 
arguments are specified, entry or * must be specified; 
otherwise, the first argument is taken as the entry point. 
Arguments are passed to the program via general register 1. 
The entry operand and any arguments become a string of 
doublewords, one argument per doubleword, and the address of 
the list is placed in general register 1. 

N o te s : 

1. Any undefined names or references specified in the files loaded 
into storage are defined as zero. Thus, if there is a call or 
branch to a subroutine from a main program, and if the subroutine 
has never been loaded, the call or branch transfers control to 
location zero of the virtual machine at execution time. 

2. Do not use the START command for programs that are generated via 
the GENMCD command with the NOHAP option. The START command does 
not execute properly for such programs. 



Responses 

DMSLIO074I EXECUTION BEGINS... 

is displayed when the designated entry point is validated, 

Other Messages and Return Codes 



| DMSLI0021E ENTRY POINT 'name' NOT FOUND RC=40 
DMSLI0055E NO ENTRY POINT DEFINED RC=40 
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Use the STATE command to verify the existence of a CHS file. The format 
of the STATE command is: 

i — — ■ 1 

| STATE | fn ft [fm] | 

i . 1 



w u er e t 

fn is the filename of the file whose existence is to be verified. 
This field must be specified. 

ft is the filetype of the file whose existence is to be verified. 
This field must be specified. 

fm is the filemode of the file whose existence is to be verified. If 
this field is omitted, all your disks are searched. 

Note: If * is specified for fn, ft, and/or fm the first file found 
satisfying the rest of the fileid is used. 

| If the filemode refers to an OS or DOS disk, the STATE command assumes 

I that the filename and filetype are related to an OS data set name or DOS 

| file-id through a previous FILEDEF. If an associated FILEDEF command 

| was not issued, you receive a FILE NOT FOUND message. 

Responses 

| DMSSTT227I PROCESSING VOLUME 'no» IN DATA SET • data set name 1 

| The specified data set has multiple volumes; the volume being 

| processing is shown in the message. The STATE command treats 

| end-of-volume as end-of-file and there is no end-of-volume 

j switching. 

| DMSSTT228I USER LABELS BYPASSED ON DATA SET 'data set name* 

| The specified data set has disk user labels; these labels are 
| skipped. 

Other Messages and Return Codes 

DMSSTT002E FILE • f n ft fm« NOT FOUND RC=28 

DMSSTT048E INVALID MODE *mode' RC-24 

DMSSTT054E INCOMPLETE FILEID SPECIFIED RC=24 

DMSSTT062E INVALID »char» IN FILEID »fn ft 1 RC=20 

DMSSTT069E DISK ■mode* NOT ACCESSED RC=36 

DMSSTT070E INVALID PARAMETER »param« RC=24 

DMSSTT229E UNSUPPORTED OS DATA SET, ERROR »code» 

| Note: You can invoke the STATE command from the terminal, from an EXEC 

| file, or as a function from a program. If STATE is invoked as a function 

I or from an EXEC file that has the &CONTROL NOMSG option in effect, the 

I DHSSTT002E FILE fn ft fm NOT FOUND error message is not issued. 
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SVCTRACE 

Use the SVCTRACE com and to trace and record intonation about 
supervisor calls occurring in your virtual machine. 

The information recorded includes the virtual storage location of the 
calling SVC instruction and the name of the called program or routine, 
the normal and error return addresses, the contents of the general and 
floating-point registers before branching to the SVC-called program and 
after returning from it, and 16 words of the parameter list which 
existed when the SVC was issued. 

To terminate tracing previously established by the SVCTRACE command, 

issue the HO or SVCTRACE OFF commands. Both SVCTRACE OFF and HO cause 

all trace information recorded up to the point they are issued to be 

printed on the virtual spooled printer. On typewriter terminals 

SVCTRACE OFF can be issued only when the keyboard is unlocked to accept 

input to the CHS command environment. To terminate tracing at any other 

| point in system processing, HO must be issued. To suspend tracing 

| temporarily during a session, interrupt processing and enter the 

| immediate command SO (Suspend Tracing) . To resume tracing that was 

j suspended with the SO command, enter the immediate command RO (Resume 

| Tracing) . 

If you issue the CHS command HX or log off the control program before 
termination of tracing set by SVCTRACE, the switches are cleared 
automatically and all recorded trace information is printed on the 
virtual spooled printer. The format of the SVCTRACE command is: 



i 1 

| SVCTrace | ( ON ) I 

I I I OFF J | 

i i 

where; 

OH starts tracing all SVC instructions issued within CHS. 

OFF stops SVC tracing. 

The printer trace output consists of the following: 

• The contents of the general registers both before the SVC-called 
program is given control and after a return from that program. 

• The contents of the general registers when the SVC handling routine 
is finished with processing. 

• The contents of the floating-point registers before the SVC-called 
program is given control and after a return from that program. 

• The contents of the floating-point registers when the SVC handling 
routine is finished processing. 

• The parameter list passed to the SVC. 
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SVCTRACE 

Responses 

A variety of information is printed whenever the 

SVCTRACE ON 

command is issued. 

The first line of trace output starts vith a -, +, or *. The fori at 
of the first line of trace output is: 

- > N/D = xxx/dd name PROM loc OLDPSN » pswl GOPSN = psw2 [RC=rc] 

where; 

indicates information recorded before processing the SVC. 

+ indicates information recorded after processing the SVC, unless 
* applies. 

* indicates information recorded after processing a CHS SVC which 
had an error return. 

H/D is an abbreviation for SVC Number and Depth (or level) . 

zxx is the number of the SVC call (they are numbered sequentially) . 

dd is the nesting level of the SVC call. 

name is the macro or routine being called. 

loc is the program location from which the SVC was issued. 

pswl is the PSN at the time the SVC was called. 

psw2 is the PSN with which the routine being called is invoked, if 
the first character of this line is a minus sign (-) . If the 
first character of this line is a plus sign or asterisk (+ or 
*) , PSN2 represents the PSN which returns control to the user. 

re is the return code from the SVC handling routine in general 
register 15. This field is omitted if the first character of 
this line is a minus sign (-) , or if this is an OS SVC call. 
For a CHS SVC, this field is if the line begins with a plus 
sign (♦) , and nonzero for an asterisk (*) . Also, this field 
eguals the contents of Register 15 in the "GPRS AFTER" line. 

The next two lines of output are the contents of the general 
registers when control is passed to the SVC handling routine. This 
output is identified at the left by ".GPRSB". The format of the output 
is: 

.GPRSB =hhhhhhhh *dddddddd* 
=hhhhhhhh *dddddddd* 

where h represents the contents of a general register in hexadecimal 
format and d represents the EBCDIC translation of the contents of a 
general register. The contents of general registers through 7 are 
printed on the first line, with the contents of registers 8 through F on 
the second line. The hexadecimal contents of the registers are printed 
first, followed by the EBCDIC translation. The EBCDIC translation is 
preceded and followed by an asterisk (*) . 
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The next line of output is the contents of general registers 0, 1, 
and 15 when control is returned to your program. The output is 
identified at the left by ".GPRS AFTER :". The format of the output is: 

.GPRS AFTER : R0-R1 = h h *dd* R15 = h *d* 

where h represents the hexadecimal contents of a general register and d 
is the EBCDIC translation of the contents of a general register. The 
only general registers that CHS routines alter are registers 0, 1, and 
15 so only those registers are printed when control returns to your 
program. The EBCDIC translation is preceded and followed by an asterisk 
(*). 

The next two lines of output are the contents of the general 
registers when the SVC handling routine is finished processing. This 
output is identified at the left by ".GPRSS." The format of the output 
is: 

.GPRSS = hhhhhhhh *dddddddd* 
=hhhhhhhh *dddddddd* 

where h represents the hexadecimal contents of a general register and d 
represents the EBCDIC translation of the contents of a general 
register. General registers through 7 are printed on the first line 
with registers 8 through F on the second line. The EBCDIC translation 
is preceded and followed by an asterisk (*) . 

The next line of output is the contents of the calling routine's 
floating-point registers. The output is identified at the left by 
".FPRS". The format of the output is: 

.FPRS = f f f f *gggg* 

where f represents the hexadecimal contents of a floating-point register 
and 3 is the EBCDIC translation of a floating-point register. Each 
floating point register is a doubleword; each f and g represents a 
doubleword of data. The EBCDIC translation is preceded and followed by 
an asterisk (*) . 

The next line of output is the contents of floating-point registers 
when the SVC-handling routine is finished processing. The output is 
identified by ".FPRSS" at the left. The format of the output is: 

.fprss = f f f f *gggg* 

where f represents the hexadecimal contents of a floating-point register 
and £ is the EBCDIC translation. Each floating-point register is a 
doubleword and each f and g represents a doubleword of data. The EBCDIC 
translation is preceded and followed by an asterisk (*) . 

The last two lines of output are only printed if the address in 
Register 1 is a valid address for the virtual machine. If printed, the 
output is the parameter list passed to the SVC. The output is 
identified by ".PARM" at the left. The output format is: 

.PARM =hhhhhhhh *dddddddd* 
=hhhhhhhh *dddddddd* 

where h represents a word of hexadecimal data and d is the EBCDIC 
translation. The parameter list is found at the address contained in 
Register 1 before control is passed to the SVC-handling program. The 
EBCDIC translation is preceded and followed by an asterisk (*) . 

Figure 31 summarizes the types of SVC trace output. 
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Identification j 



Comments 



:\ 



N/D 



.GPRSB 
.GPRS AFTER 
.GPRSS 
.PPRS 



.FPRSS 



PARM 



IThe SVC and the routine which issued the SVC, 



IContents of general registers when control is passed 
to the SVC handling routine. 

Contents of general registers 0, 1, and 15 when 
control is returned to your program. 

IContents of the general registers when the SVC 
handling routine is finished processing. 

Contents of floating-point registers before the 
SVC-called program is given control and after 
returning from that program. 

IContents of the floating— point registers when the 
SVC handling routine is finished processing. 

|The parameter list, when one is passed to the SVC. 



Figure 31. Summary of SVC Trace Output Lines 



Error Messages and Return Codes 



DMSOVR014E INVALID FUNCTION 'function' RC=24 

DMSOVR047E NO FUNCTION SPECIFIED RC=24 

DMSOVR10US EBROR «nn' READING FILE • DMSOVR MODULE' ON DISK RC=100 

DMSOVR109S VIRTUAL STORAGE CAPACITY EXCEEDED RC=104 
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SYNONYM 



Use the SYNONYM command to invoke a table of synonyms to be used with, 
or in place of, the CMS command names. You create the table yourself 
using the CMS Editor. The form for specifying the entries for the table 
is described under "The User Synonym Table." 

The names you define can be used either instead of or in conjunction 
with the standard CMS command truncations. However, no matter what 
truncations, synonyms, or truncations of the synonyms are in effect, the 
full real name of the command is always operative. The format of the 
SYNONYM command is: 



SYNonym 



r r r -m 

I I ft I Ml 

|fn I SYNONYM |fm||| [ (options ...[)] ] 

I I liil | I 

L L L JJJ 

r t 

2E£ions: ISTD | [CLEAR] 

|NOSTD| 

L J 



where: 
fn 

ft 

fm 



is the filename of the file you created to contain the 
synonyms. 

is the filetype of the file containing your synonyms. The 
filetype must be SYNONYM; of omitted, SYNONYM is assumed. 



is the filemode of the file containing your synonyms, 
omitted, A1 is assumed. 



If 



Options 



STD specifies that standard CMS abbreviations are operative. 

NOSTD standard CMS abbreviations are not to be used. (But the 
full CMS command and the synonyms you defined can still 
be used.) 

CLEAR removes any synonym table set by a previously entered 
SYNONYM command. 

I The SYNONYM command specified with no operands can be used to nullify 
| the synonyms invoked by a preceding SYNONYM command; that is, you can 
| "turn off" a table of synonyms. 

Note : The SET ABBREV ON or OFF command, in conjunction with the SYNONYM 
command, determines which standard and user-defined forms of a 
particular CMS command are acceptable. 
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THE USER SYNONYM TABLE 

You create the synonym table using the CMS Editor. The table must be a 
file with the filetype SYNONYM. The file consists of 80-byte 
fixed-length records in free-form format with columns 73-80 ignored. 
The format for each record is: 



| systemcommand | usersynonym | count 

L 



where : 

systemcommand is the name of the CMS command for which you are creating 
a synonym. 

usersynonym is the synonym you are creating for a CMS command. When 
you create the synonym, you must follow the same syntax 
rules as for commands, that is, you must use the character 
set used to create commands, the synonym may be no longer 
than eight characters, and so on. For more details on 
syntax rules for commands, see "Section 2: VM/370 CP and 
CMS Command Languages." 

count is the minimum number of characters that must be entered 

for the synonym to be accepted by CMS. If omitted, the 

entire synonym must be entered (see the following 
example) . 

A table of command synonyms is built from the contents of this file. 
You may have several SYNONYM files but only one may be active at a time. 
Por example, if the synonym file contains: 

MOVEFILE MVIT 

The synonym MVIT can be entered as a command name to execute the 
MOVEFILE command. It cannot be truncated since no count is specified. 

ACCESS GETDISK 3 

The synonyms GET, GETD, GETDI, GETDIS, or GETDISK can be entered as 
the command name instead of ACCESS. 



lk§ JJeljLtiojlshiE Between the SET ABBREV and SYNONYM Commands 

There is a system synonym abbreviation table for the FILEDEF command. 
The default values of the SET and SYNONYM commands are such that the 
system synonym abbreviation table is available unless otherwise 
specified. 

The system synonym abbreviation table for the FILEDEF command states 
that FI is the minimum truncation. Therefore, the acceptable 
abbreviations for FILEDEF are: FI, FIL, FILE, FILED, FILEDE, and 
FILEDEF. The system synomym abbreviation table is available whenever 
both SET ABBREV ON and SYNONYM (STD) are in effect. 

Assume that the user-defined table has the file identification 
USERTAB SYNONYM A. Further assume that this synonym table has the 
following entry: 
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GC20-1804-3 Page Modified by TNL GN20-2659 
SYNONYM 

FILEDEF USENAME 3 

Then, USENAME is a synonym for FILEDEF, and acceptable truncations of 
OSENAME are: USE, USEN, USENA, USENAM, and USENAME. The user synonym 
abbreviation table is available whenever both SET ABBBEV ON and SYNONYM 
USERTAB are specified. 

No matter what synonyms and truncations are defined, the full real 
name of the command is always in effect. 

Figure 32 lists the forms of the system command and user synonym 
available for the various combinations of the SET ABBREV and SYNONYM 
commands . 



Responses 



| DMSSYN712I NO SYNONYMS (DMSINA NOT IN NUCLEUS) 

The system routine which handles SYNONYM processing is not in the 
system. 



Q£ii®I M6§§53®s and Return Codes 



DMS3YN002E FILE ! fn ft fm' NOT FOUND RC=28 

DMSSYN003E INVALID OPTION 'option' RC=24 

DMSSYN007E FILE »fn ft f m • NOT FIXED, 80 CHAR RECORDS RC=32 

DMSSYN032E INVALID FILETYPE 'ft' RC=24 

DMSSYN056E FILE «fn ft fm' CONTAINS INVALID RECORD FORMATS RC=32 

DMSSYN10US ERROR ' nn « READING FILE • f n ft fm« FROM DISK RC=100 
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r — — - - - — —i 

| | Acceptable | | 
| j Command | I 
| Options | Forms | Comments | 


i SET ABBREV Ci j FI j The ABBREV OH option of the SET | 
j SYH USERTAB (STD | FIL | command and the STD option of the j 
| j | . | SYHOHYM command make the system | 
j j . | table available. The user synonym, j 
| 1 . 1 USEHAHE is available | 
j j FILEDEF | because the synonym table j 

1 1 I1CO 1 fflCDDIIlDI 1« nn<vxj<«o^ >- i.1 — • 

j { UbJS J ("bijulav) 13 afCblLieu UU LUt! j 

I j USEH | SYHOHYM command. The truncations | 
| 1*1 for USEHAHE are available because | 
1 1*1 SET ABBREV OH was specified with j 
{ ! - ! the USERTAB also available. j 
| | USEHAHE | | 


| SET ABBREV OFF | FILEDEF |The user-defined synonym, USEHAHE, | 
| SYH USERTAB (STD j USEHAHE | is permitted because the user | 
| | | synonym table (USERTAB) is speci— j 
| | | fied on the SYHOHYH command. Ho | 
j | | system or user truncations are j 
| | | permitted. | 


| SET ABBREV OH } FILEDEF | The system synonym table is un— j 
| SYH USERTAB (HOSTD| USE | available because the HOSTD option | 
| | USEH | is specified on the SYHOHYH com- | 
j 1*1 nand. The user synonym, USEHAHE, j 
| | 1 is available because the user syno— | 
| | . | nym table (USERTAB) is specified on j 
| | USEHAHE | the SYHOHYH command and the trun- | 
| j | cations of USEHAHE are permitted | 
| j | because SET ABBREV OH is specified | 
| 1 | with USERTAB also available. j 


1 SET ABBREV OFF | FILEDEF |The system synonym table is made j 
| SYH USERTAB (HOSTD | USEHAHE | unavailable either by the SET | 
| j | ABBREV OFF command or by the SYH | 
| | | (HOSTD command. The synonym, | 
| | | USEHAHE, is permitted because the I 
| | | user— defined synonym table | 
j | | (USERTAB) is specified on the | 
| | | SYHOHYH command. The truncations | 
1 | | for USEHAHE are not permitted j 
| j | because the SET ABBREV OFF option j 
I | | is in effect. j 


j SET ABBREV OH | FI |The user-defined table is now un- j 
| SYH (CLEAR STD j FIL | available. The system synonym j 
| 1 • 1 table is available because both | 
| j . | the ABBREV OH option of the SET j 
| 1*1 command and the STD option of the | 
| | FILEDEF | SYHOHYH command are specified. | 


| SET ABBREV OFF | FILEDEF | Because CLEAR is specified on the | 
| SYH (CLEAR STD | | SYHOHYH command, the synonym and | 


| SET ABBREV OH | | available. Either the SET ABBREV | 
| SYH (CLEAR HOSTD | | OFF command or the SYHOHYH (HOSTD | 


| SET ABBREV OFF | | table unavailable. j 
| SYH (CLEAR HOSTD | | I 



| Figure 32. System and user Truncations 
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TAPE 



Use the TAPE command to dump CMS-f ormatted files from disk to tape, load 
previously dumped files from tape to disk, and perform various control 
operations on a specified tape drive. TAPE is used solely for CMS 
files; therefore, the files on tape are in a unique CBS format. The 
TAPE command does not process multivolume files. Disk files to be 
dumped can contain either fixed- or variable-length records. The format 
of the TAPE command is: 



TAPE 



DUMP 



{"}{"} 



r l 

I fa I 

1*1 [ (optionA optionB optionD[) ]] 

L J 



LOAD Ijfn) /ft) |fm| | [ (optionB optionC optionD[)]]j 
/ I* J IA | | 



a* 

L 



L J J 



SCAD 



SKIP 

MODESET 

r t 

tapcmd |n| 

111 

L J 



!{?}{?} 

{?}{:*} 



[ (optionB optionC optionD[) ]] 
[(optionB optionC optionD[)]] 



[ (optionD[)]] 
[ (optionD[) ]] 



\ 

r t 

optionA: |WTM | 
I £ Q1M I 

L J 

r t 

optionB: |NOPBint| 
IPBint | 

I J-SIJ! I 
I DISK | 

L J 

r t 

optionC: |EOT | 
| EOF n| 
IIPJ II 

L ~J 

rr m r n 

optionD: | |TAPi | I |7TBACK| [DEN nnn ] [ TRTCH xx] 

HUH II |9TRACK| 
|L j , t J 

lr il 

llcuu || 

11181 II 

LL J J 



where: 



DDHP U fn Hr}[^] 



dumps one or more 
identification must be 



disk files to tape. The file 
specified. If the asterisk or mode 
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letter only is coded, all files that satisfy the resulting 
file identification are dumped. 

The filename (fn) and filetype (ft) of the files to be 
dusmed must be specified* The filemods (f— } of the files to 
be dumped is optional. The filemode letter indicates the 
source disk for dumping; the filemode number indicates that 
only files with that number are to be dumped. A blank 
filemode number indicates that all files satisfying the fn 
and ft specifications are to be dumped. 

writes tape files to disk. If file identification is 
specified, only that one file is loaded. The file 
identification is filename (fn) , filetype (ft) , and filemode 
(fm) . If the option EOF n is specified and no file 
identification is entered, n tape files are written to 
disk. If an asterisk (*) is specified for fn or ft, all 
files within EOF n that satisfy the resulting file 
identification are loaded. 

The files are written to the disk indicated by the fileiode 
letter. The filemode number, if entered, indicates that 
only files with that filemode number are to be loaded. A 
blank filemode number indicates that all files satisfying 
the fn and ft specifications are to be loaded. 

SC»H [{'■}{«}] 

displays at the terminal (unless NOPRINT, PRIST or DISK is 
specified) the names of the files on tape. If DISK is 
specified the list of file identifiers is written to a file 
named TAPE HAP. If file identification (filename, fn, and 
filetype, ft) is specified, scanning stops upon encountering 
that file. If not specified, scanning occurs over n tape 
marks as specified by the option EOF n. 

SKIP /fnWft 



W.*} 



positions tne rape at a speciriea point, depending upon 
other options and operands. If file identification 
(filename, fn, and filetype, ft) is entered, the tape is 
positioned after the specified file; if EOF n is entered, 
the tape is positioned after n tape marks. 

MODESET sets the values specified by the DEN, TRACK, and TRTCH 
options. These values remain in effect for the specified 
tape until they are changed in a subsequent TAPE command. 

r t 
tapcmd |n| specifies a tape control function (tapcmd) to be executed n 
121 times (default is 1 if n is not specified) : 



L J 



Tapcmd Action 

6SF backspace n tape marks 

BSR backspace n tape records 

ERG erase gap 

FSF forward space n tape marks 

FSR forward space n tape records 

REW rewind tape to load point 

RUN rewind tape and unload 

WTM write n tape marks 
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Options 



Mote; If conflicting options are specified, the last one entered is 
in effect. 



NTH 



writes a tape lark on the tape after each file dumped. 



NORTH 



writes a tape mark after each file is dumped, then 
backspaces over the tape nark so that subsequent files 
written on the tape are not separated by tape marks. 



NOPRINT does not spool the list of files dumped, loaded, scanned, 
or skipped to the printer. 



PRINT 



spools the list of files dumped, loaded, scanned, or 
skipped to the printer. 



TERM 



displays a list of files dumped, loaded, scanned, or 
skipped at the terminal. 



DISK 



creates a disk file containing the list of files dumped, 
loaded, scanned, or skipped. The disk file has the file 
identification of TAPE MAP. 



EOT 



reads the tape until an end-of-tape indication is 
received. 



EOF n 
EOF 1 



reads the tape through a maximum of n tape marks. Default 
is EOF 1. 



TAPi 
cuu 



7TRACK 



specifies the symbolic tape identification or the actual 
device address of the tape to be read from or written to. 
The default is TAP1 or 181. The unit specified by cuu 
must previously have been attached to your CHS virtual 
machine before any tape I/O operation can be attempted. 
Only symbol names TAP1 through TAP4 and virtual device 
addresses 181 through 184 are supported. 

specifies a 7 track tape. Odd parity, data convert on, 
and translate off are assumed unless TRTCH is specified. 



9TRACK specifies a 9 track tape. 

DEN nnnn is the tape density where nnnn is 200, 556, 800, 1600, or 
6250. If 200 or 556 is specified, 7TRACK is assumed. If 
1600 or 6250 is specified, 9TRACK is assumed; if 800 is 
specified, 9TRACK is assumed unless 7TRACK is specified. 
In the case of dual-density drives, 1600 is the default. 

TRTCH xx is the tape recording technique for 7 track tape. If 
TRTCH is specified, 7TRACK is assumed. One of the 
following must be specified as xx: 
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xx Meaning 

odd parity, data convert off r translate off 

OC odd parity, data convert on, translate off 

OT odd parity, data convert off, translate on 

E even parity, data convert off, translate off 

ET even parity, data convert off, translate on 

Format of Tape Created by. TAPE DUMP Comman d 

Tape records written by the CHS TAPE DUMP command are 805 bytes long. 
The first character is a binary 2 (X , 02 l ), followed by the characters 
CMS and an EBCDIC blank (X^O 1 ), followed by 800 bytes of file data 
packed without regard for logical record length. In the final record, 
the character N replaces the blank after CMS, and the data area contains 
CMS file directory information. 



I TAPE Command Restrictions 



If a tape contains large files that would not fit on disk, the tape load 
operation is terminated. To prevent this, when you dump the files, 
separate logical files by tape marks, then forward space to the 
appropriate file. 

Because the CMS file directory is the last record of the file, the 
TAPE command creates a separate workfile so that backspacing and 
rereading can be avoided when the disk file is built. If the load 
criteria is not satisfied the workfile is erased; if it is satisfied the 
workfile is renamed. 

The RUN option (rewind and unload) indicates completion before the 
physical operation is completed. Thus, a subseguent operation to the 
same physical device may encounter a device busy situation. The TAPE 
command creates a work file TAPE CMS0T1 which may exist if a previous 
TAPE command has abnormally terminated. If the work file is 
accidentally dumped to tape and subseguently loaded, it appears on your 



Responses 



DMSTPE701I HULL FILE 

A final record was encountered and no prior records were read in a 
TAPE LOAD operation. No file is created on disk. 

If the TERM option is in effect, the following is displayed at the 
terminal depending on the operation specified: 



LOADING...., 
fn ft fm 



SKIPPING.... 
fn ft fm 
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DUMPING...., 
fn ft fl 



SCABBING.... 
fn ft fi 



When a tape nark is encountered the following 
terminal if the TERM option is specified: 

EBD-OF-FILE OR EBD-OF-TAPE 



is displayed at the 



| If a tape contains large files that would not fit on disk, the tape 

| load operation is terminated. To prevent this when you dump the files 

| separate logical files by tape narks, then forward space to the 

I appropriate file. 



°-!Ji6£ ^®§§3fl§§ a nd Return Codes 



DMSTPE002D 
DMSTPE003E 
DMSTPE010E 
DMSTPEQIttE 
DMSTPE017E 
DMSTPE023E 
DMSTPE027E 
DMSTPE029E 
DHSTPE037E 
DMSTPE042E 
DMSTPE043E 
DMSTPE047E 
DMSTPE048E 
DMSTPE057E 
DHSTPE058E 
DMSTPE070E 
DMSTPE104S 
DHSTPE105S 
DMSTPE110S 
DMSTPE111S 
DMSTPE113S 

| DMSTPE115S 

I 



RC=2U 
RC=24 

RC=24 



RC=36 



FILE (S) »fn ft fn« NOT FOOND RC=28 

INVALID OPTION 'option 1 RC=2U 

PREMATURE EOF OH FILE • f n ft fn» RC=40 

INVALID FUNCTION • function 1 

INVALID DEVICE ADDRESS »cuu» 

HO FILETYPE SPECIFIED RC=24 

INVALID DEVICE • device name* 

INVALID PARAMETER «paran» IN THE OPTION • option 1 FIELD 

DISK 'node 1 IS READ/ONLY RC=36 

BO FILEID SPECIFIED RC=24 

•TAPn(cuu) • IS FILE PROTECTED 

BO FUBCTIOB SPECIFIED RC=24 

IBVALID MODE «node» RC=24 

IBVALID RECORD FORMAT RC=32 

EBD-OF-FILE OR EHD-OF-TAPE RC=40 

IBVALID PARAMETER «paran« RC=2U 

ERROR *nn* READIBG FILE *fn ft fa* 

ERROR »nn» HRITIBG FILE • f n ft fn* 

ERROR READIHG »TAPn(cuu)» RC=100 

ERROR HRITIHG »TAPn (cuu) • RC=100 

TAPn(cuu) HOT ATTACHED RC-100 

{COHVERSIOB|7 TRACK} FEATURE 



RC=24 



FROM DISK RC=100 
OB DISK RC=100 



BOT 



SUPPORTED 



OB 



(TRABSLATIOB|DUAL-DEHSITY) DEVICE »CUU» RC=88 
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TAPPDS 



Use the TAPPDS command to create CHS disk files from either tapes in 

unblocked card-image format that are produced by the OS IEBPTPCH service 

program or from tapes in the OS IBBUPDTE service program control file 

| format, either blocked or unblocked. Using the TAPPDS command, you can 

| also read unloaded partitioned data sets (PDS) from a tape created by 

| the OS IEHHOVE service program, and create a CHS disk file for each 

I member of the data set. The tape can be unlabeled or it can contain OS 

standard labels. The format of the TAPPDS command is: 



TAPPDS 



r r r nn 

|fn |ft IfmlM 

i * I * illiM 

I I I* III 

L L L JJJ 



[ (options. . .[) ]] 



options : | PDS | 
INOPDS | 
| UPDATE | 

L J 

r i 

|EHD | 
I HOE HP I 

L J 



r t 

|C0L1 | 
| HO COL J | 

L J 



r t 

IHAXTEH | 
IHOHAXTEHI 

u J 



r t 

|TAPn| 
I TAP 1| 

I J 



where: 
fn 



is the filename of the disk file to be created. This 
field has meaning only if the HOPDS option is selected 
(that is, the tape does not contain members of a 
partitioned data set) . If the tape does contain members 
of a partitioned data set (PDS) , an asterisk must be 
specified; one file is created for each member with a 
filename the same as the member name. If HOPDS or UPDATE 
is specified, the default filename is TAPPDS. The 
default is assumed if the filename is omitted or coded as 
*. 



ft 



is the filetype of the newly created files. The default 
filetypes are CHSUT1 (for PDS or HOPDS) and ASSEHBLE (for 
UPDATE) . The defaults are used if ft is omitted or 
specified as *. 



fm 



is the mode of the disk to contain the new files. The 
default filemode is A1 if this field is omitted or 
specified as an asterisk (*) . 



Options 



If conflicting options are specified, the last one entered is used. 
All options, except TAPn, are ignored when unloaded PDS tapes are 
read. 



PDS 



indicates that the tape contains members of an OS 
partitioned data set, each preceded by a "HEHBER 
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NAHE=name" statement. The tape must have been created 
by the OS IBBPTPCB service program if this option is 
specified. 



HOPDS 



indicates that the tape contains one file. 



UPDATE 



provides the "./ ADD" function of the OS IEBOPDTE 
service program in your CHS virtual machine. It 
indicates that the optional material which is in 
IEBOPDTE control file format is to be loaded onto disk 
as CHS files. The filename of the new disk file is 
taken from the NAME= parameter in the "./ ADD" 
record. The tape input file can be blocked or 
unblocked. All records are written onto the CHS disk 
in fixed- length, 80-byte format. 

The BED option is disabled when UPDATE is specified. 
The C0L1 option should be used with UPDATE so that the 
scanning of the data starts at column one. The "./ " 
must appear in columns 1-3. All records that do not 
contain "./ " in columns 1-3 which TAPPDS encounters 
after an initial "./ ADD" record, are written onto 
disk. Conversely, if "./ ADD" is not found, the file 
is not created on disk. The "./ " records are not 
written as part of the file on disk. 

An "./ BHDUP" record causes TAPPDS to close the 
current file and stop processing without repositioning 
the tape; also, a single tape mark has the same 
effect. 

The optional •label 1 in columns 3-10 of a "./ " record 
in an IEBUPDTE control file is not recognized by 
TAPPDS. The record is treated as a data record and 
included in the CHS disk file. 

For the •'./ ADD" record, if the HAHE= parameter is 
missing or followed by a blank, TAPPDS uses the 
default filename "TAPPDS" for the CHS disk file. If 
this condition occurs more than once during command 
execution, then upon completion of the TAPPDS command 
only the last member "./ ADD" without a valid NAHE= 
parameter is on your disk with the default filename. 



COL1 
NOCOL1 



TAPn 
TAP1 



takes data from columns 1-80; column 1 contains data. 



takes data from columns 2-80: column 1 contains 
control character information. This is the format 
produced by the OS IEBPTPCH service program. 

is the tape unit number. TAP1 is the default tape unit 
number, which corresponds to the virtual address 181. 
There are four possible values of n: TAP1 through 
TAP4, indicating virtual tape drives 181 through 184. 



END 



considers an EHD statement a delimiter for the current 
member. 
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HOBHD specifies that EHD statements are not to be treated as 

■ember delimiters, but are to be processed as text. 

MAXTEN reads up to ten members. This is valid only if the 
PDS option is selected. 

NOHAXTEN reads any number of members. 



Responses 

DMSTPD703I FILB »fn ft [£■]• COPIED 

The named file is copied to disk. 

DHSTPD707I TBH FILES COPIED 

MAXTEN was specified and ten members are copied, 



If the tape being read contains standard OS labels, the labels are 
displayed at the terminal. 



Other Messages and Return Codes 



DHSTPD003E INVALID OPTION • option* RC=24 

DHSTPD058E EHD-OF-FILE OR END-OF-TAPE RC=40 

DMSTPD105S ERROR *nn* WRITING FILB *fn ft fm* ON DISK RC-100 

DMSTPD110S ERROR «nn» READING •TAPn(cuu) 1 RC=100 
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TXTLIB 



Use the TXTLIB command to update CHS text libraries. A text library is 
one which is to be searched for Missing subroutines in LOAD and INCLUDE 
commands. (See Bote 1.) 

A text library is a file that has a filetype of TXTLIB and contains a 
dictionary and one or more relocatable object programs obtained from CHS 
files having a filetype of TEXT. 

The TXTLIB command: 

• Generates a text library. 

• Adds to an existing text library. 

• Deletes from an existing text library. 

• Lists the names and aliases or entry points and control section names 
and the location of the TEXT files included in the text library. 

The format of the TXTLIB command is: 




libname fn1 [fn2 . ..] 
libname fn1 [fn2 . ..] 

libname membernamel [membername2 

r t 

| (TERH) | 

libname | (PRINT) | 

I (DISK) | 

L J 



•] 



where; 

GEN libname fn1 [ f n2 ...] 

generates a text library with the specified filename (libname) 
and a filetype of TXTLIB from the TEXT files specified by fn1 
fn2... If a file exists with the identification libname TXTLIB, 
it is erased and a new one is created. 

ADD libname fn1 [fn2 •••] 

appends the contents of the files specified by fn1 fn2... to the 
end of the existing library with the file identification libname 
TXTLIB. No checking for duplicate names, aliases, entry points, 
or CSECT names is performed. 

DEL libname membernamel [ member name2. . . ] 

removes the text decks with member names (membernamel, 
membername2.. .) from the directory of the text library, libname 
TXTLIB. If two members exist with the specified membername, only 
the first one encountered is deleted (unless the membername is 
given twice in the argument list) . 

Deletions must be performed on the NAHE or first Section 
Definition (SD) in the text deck. A deletion for an alias name 
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or subsequent entry point results in a not found message with no 
change to the member. DEL removes the member and all references 
to it. 

The file is automatically compressed so that space occupied by 
the deleted members can be reused. 



I (TERM) | 

HAP libname | (PBIHT) | 

i <P|SK) I 

L J 

generates the file libname HAP on the primary disk, if a file 
already exists with the same identification, it is erased and the 
new file is created. The libname HAP file contains the same 
information as that in the dictionary of the specified text library 
and is in the format of a list of entry points and control section 
names that reside in the text library, and their location or index 
in the file. The options on the command line are examined to 
determine if the HAP is to be directed to the terminal (TERH) , or 
the printer (PRINT) , or is to remain on disk (DISK) . 

The HAP operand of the TXTLIB command displays a statement 
indicating the total number of entry points and control section 
names that currently exist in the TXTLIB file. 



Notes 

1. The total number of members in the TXTLIB file cannot exceed 1000. 
When this number is reached, an error message is displayed. The 
text library created includes all the text files entered up to (but 
not including) the one that caused the overflow. 

2. OS Linkage Editor ENTRY, ALIAS, and NAHE control statement are 
accepted. If a NAHE statement is detected, only ALIAS and NAHE 
'names* are included in the dictionary for that text deck. 
Deletions must be performed on the NAHE 'name*. The total number 
of ALIAS names cannot exceed sixteen names per text deck. 

3. Unlike OS STEPLIB entries, CHS TXTLIB members are not fully 
link-edited. The loader, for either an explicit or dynamic load, 
attempts to resolve all external references. For a dynamic load, 
if all VCONs cannot be resolved within a member, an incorrect entry 
point might be returned. You should explicitly load those 
subroutines by either CHS LOAD and INCLUDE commands or by a VCON in 
the program. 



XXX ENTRIES IN LIBRARY 



When TXTLIB is issued, the contents of the dictionary of the 

specified text library are displayed at the terminal. The 

number of entries in the text library (xxx) is displayed at the 
terminal when the TXTLIB HAP command is issued. 
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Other Messages and Return Codes 

DMSLBT001E HO FILENAME SPECIFIED RC=24 

DMSLBT002E FILE • f n £t« NOT FOUND RC=28 

DHSLBT002N FILE »fn ft« NOT FOUND RC=4 

DMSLBT003E INVALID OPTION 'option* RC=24 

DMSLBT013E MEMBER 'naie' NOT FOUND IN LIBRARY »fn ft fm» RC=32 

DMSLBT014E INVALID FUNCTION ■function* RC=24 

DMSLBT046E NO LIBRARY NAME SPECIFIED RC=24 

DMSLBT047E HO FUNCTION SPECIFIED RC=24 

DMSLBT056E FILE ' f n ft fa 1 CONTAINS [{ NAME| ALIAS | ENTRY | ESD } ] INVALID 

RECORD FOBMATS RC=32 
DMSLBT056N FILE »fn ft fm» CONTAINS [{ NAME| ALIAS | ENTRY | ESD } ] INVALID 

RECORD FORMATS RC=4 
DMSLBT10US ERROR »nn» READING FILE ■ f n ft fm 1 FROM DISK RC=100 
DMSLBT105S ERROR »nn» WRITING FILE • f n ft fm 1 OH DISK RC=100 
DMSLBT106S NUMBER OF MEMBER NAMES EXCEEDS MAX «nnnn». FILE »fn ft» NOT 

ADDED RC=88 
DMSLBT213N LIBRARY • f n ft fm» NOT CREATED RC=4 
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TYPE 



Dse the TYPE command to display all or part of a specified file at the 
terminal in either EBCDIC or the hexadecimal representation of the 
EBCDIC code. The format of the TYPE command is: 



r r n 

Type | fn ft [fm] | red |recn| | [ (options. ..[) ] ] 

1*1*11 

111 II 

L L JJ r r t t 

options: | (xxxxx) lyyyyvl I 

ICOL^ V- | "j | 

I ( 1 ) Urecli | 

L L J J 



THEX] 



| MEMBER <J \ | 

| I name ) | 



where: 
fn 



is the filename of the file to be displayed, 
must be specified. 



This field 



ft 



is the filetype of the file to 
must be specified. 



be displayed. This field 



fm 



is the filemode of the file to be displayed. If this field 
is omitted, the A-disk and its extensions are searched to 
locate the file. In the case of files with duplicate 
filename and filetype, only the first file found is 



displayed 



red 



is the record number of the first record to be displayed. 
This field cannot contain special characters. If red is 
greater than the number of records in the file, the file 
length is assumed. If this field is omitted or entered as 
an asterisk, a record number of 1 is assumed. 



recn 



is the record number of the last record to be displayed. 
This value cannot contain embedded commas. If this field is 
not specified or is entered as an asterisk, display 
continues until end of file is reached. 
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Options 

I col xxxxx yyyyy 

| displays only certain positions of each record, xxxxx 

| specifies the beginning position and yyyyy the ending 

| position of the field within the record which is to be 

displayed. If a field is not specified, the entire 
record is displayed unless the filetype is LISTING, in 
which case the first position of each record is not 
displayed, since it is assumed to be a carriage control 
character. 

BEX displays the file in hexadecimal format. 

| MEMBER i * ) displays member (s) of a library. If the file specified 
| MEM (name/ is a library, a MEMBER entry can be specified. If an 
| asterisk (*) is specified, all members of the library 

are displayed. If a name is specified, only that 

particular member is displayed. 



Re§£onse 

The file is displayed at the terminal according to the given 
specifications . 



Error Messages and Return Codes 

DMSTYP002E FILE »fn ft fm' HOT FOUND RC=28 

DMSTYP003E INVALID OPTION 'option' RC=24 

DMSTYP005E INVALID 'option' SPECIFIED RC=24 

DMSTYP009E COLUMN 'col' EXCEEDS RECORD LENGTB RC=24 

DMSTYP013E MEMBER 'name' NOT FOUND IN LIBRARY RC=32 

DMSTYP029E INVALID PARAMETER 'param' [IN THE OPTION 'option' FIELD] 

RC=24 
DHSTYP033E FILE »fn ft fm' IS NOT A LIBRARY RC=32 
DMSTYP039E NO ENTRIES IN LIBRARY 'fn ft fm« RC=32 
DMSTYP049E INVALID LINE NUMBER 'line number' RC=24 
DMSTYP054E INCOMPLETE FILEID SPECIFIED RC=24 
DMSTYP062E INVALID * IN FILEID RC=20 
DMSTYP104S ERROR 'nn» READING FILE »fn ft fm' FROM DISK RC=100 
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UPDATE 



rrpnjiTP 



Use the UPDATE command to modify program source files. The source files 
should be stored as 80-character card-image files with sequence fields 
in record positions 73 to 80. The UPDATE command accepts a source input 
file and one or more files containing update control statements and 






output file, an update log file indicating what changes, if any, were 
made, and an update record file if more than a single update file is 
applied to the input file. 



Updates may be applied either permanently (that is, the updated 
output file replaces the source input file) , or temporarily, in which 
case the updated output file has the name '$fn*, where *fn' is the file 
name of the input source file. The format of the UPDATE command is: 















" -1 


j Update 


fn1 jftl 

| ASSEMBLE 


r 

|f mi [fn2 

111 

L 


[ft2 [fm2]]]|| [ (opt 

II 
j j 


ions. . • [) ] ] 






options: 


r t 
| REP | 

| NO RE£ I 

L J 


r i 
| SE0.8 | 
|NOSEQ8| 

L J 


r i 
IIHC | 
|N0INC| 

L J 


r i 
|CTL | 
|NOCTL| 

L J 








r t 
|STK | 
INOSTKJ 

L J 


r t 

|TERM | 
INOTERM | 

L J 


r t 

IDISK | 
IPRINTI 

L J 


r t 

ISTOR | 
|NOSTOR| 

L J 


J 



where: 



fn1 ft1 fil 



fn2 ft2 fm2 



is the filename, filetype, and filemode of the source input 
file. If the filemode or filetype is omitted, 'AT and 
'ASSEMBLE' are assumed, respectively. 



is the filename, filetype, and filemode of the file 
containing the update control statements and updated source 
records, or, if the CTL option is specified, specifies the 
filename, filetype, and filemode of the update control file 
to be used for a multiple update. The defaults are fn1 
UPDATE A1 if NOCTL is in effect, and fn1 CNTRL A1 if CTL is 
specified. 



Options 



REP replaces with the source input file with the updated 
source file. 

UPJIEP retains the old file in its original form, and assigns a 
different filename to the new file, consisting of a 
dollar sign ($) plus the first seven characters of the 
input filename (fn1) . 
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UPDATE 



SE0.8 



N0SEQ8 



I8C 



NOINC 



CTL 



NCCTL 



STK 



NOSTK 



TERM 



NCTERM 



DISK 



PRINT 



STOR 



specifies that the entire sequence field (columns 73 
through 80) contains an 8-digit sequence number on every 
record of source input. 

specifies that columns 73-75 contain a 3 character label 
field, and that the sequence number is a 5-digit value in 
columns 76-80. 

puts sequence numbers in columns 73 through 80 of each 
updated record inserted from the update file. 

puts asterisks (********) in the seguence number field of 
each updated record inserted from the update file. 

specifies that fn2, ft2, and fm2 describe an update 
control file for applying multiple update files to the 
source input file (see the "Control statement Formats" 
section that follows) . 

Note^ The CTL option implies the INC option. 

specifies that a single update file is to be applied to 
the source input file. 

stacks information resulting from a multiple update at 
your CMS console. This information can then be read by a 
CMS EXEC procedure. STK is used only with the CTL 
option. 

specifies that no external communication of the multiple 
update results is desired. 

displays warning messages at the terminal whenever a 
sequence or update control card error is discovered. 
(Such warning messages appear in the update log, whether 
they are displayed at the terminal or not.) 

suppresses the displaying of warning messages at the 
terminal. However, error messages which terminate the 
entire update procedure are displayed at the terminal. 

places the update log file on disk. This file has a file 
identification "fn UPDLOG", where "fn" is the filename of 
the file being updated. 



prints the update log file directly on 
printer. 



the virtual 



NCSTOR 



specifies that the source input file is to be read into 
storage and the updates performed in storage prior to 
placing the updated source file on disk. This option is 
meaningful only when used in conjunction with CTL option 
since the benefit of increased processing speed is 
realized when processing multiple updates. STOR is the 
default when CTL is specified. 

specifies that no updating is to take place in storage. 
NOSTOR is the default when performing single updates or 
when CTL is omitted from the command line. 
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UPDATE 



Control st.ateiei>t.s 



The UPDATE control statements let you insert, delete and replace source 
records, as well as resequence the output file. All UPDATE control 
statements are identified by the characters • ./• in columns 1 and 2 of 
the 80-byte record, followed by one or more blanks and a maximum of 6 
additional, blank-delimited fields. Control statement data must not 
extend beyond column 50. All references to the sequence field of an 
input record refer to the numeric data in columns 73-80 of the source 
record, or columns 76-80 if N0SEQ8 is specified. Leading zeros in 
sequence fields are not required. If no sequence numbers exist in an 
input file, a preliminary UPDATE with only the *./ S' control statement 
can be used to establish file sequencing. 
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Any sequence fields in the update control statements are ignored; if 
the NOINC option is specified, all sequence fields in the update file 
are ignored, including those on inserted records. If the INC option is 
specified, sequence fields for the inserted records are either generated 
by UPDATE, if the dollar-sign ($) delimiter is used, or are included 
intact from the update file if the dollar sign ($) is not used. 



Changes are made sequentially in a single pass through the input and 
update files; an error condition results if any sequence errors occur in 
the update control statements, and warnings are issued if an error is 
detected in the sequencing of the input file. Any source input records 
with a sequence field of eight blanks are skipped, without any 
indication of a sequence error, such records may be replaced or deleted 
only if they occur within a range of records that are being replaced or 
deleted entirely and if that range has limits with valid sequence 
numbers. There is no means provided for specifying a seguence field of 
blanks on an update control statement. 



Control Statement Formats 



Sequence Control Statement — resequences the updated source output file 
in columns 73-80 (if SEQ8 is specified) , or in columns 76-80 with the 
label placed in columns 73-75 (if N0SEQ8 is specified) . If this 
statement is included in the update file, it must be the first control 
statement. The format of the Sequence control statement is: 



| ./ S [seqstrt [seqincr [label]]] 



where ; 

seqstrt a one- to eight-digit numeric field specifying the 
first decimal sequence number to be used. The default 
value is 1000 if SEQ8 is specified and 10 if N0SEQ8 is 
specified. 

seqincr a one- to eight-digit numeric field specifying the 
decimal increment for resequencing the output file. 
The default is the •seqstrt 1 value. 



label 



a 3-character field to be duplicated in columns 73-75 
of each source record if N0SEQ8 is specified. The 
default value is the first three characters of the 
input filename (fn1) . 



An error is indicated if any valid control statement precedes the 
./ S statement in the update file, and the resequence operation is 
suppressed. 



Each source record is resequenced in columns 73-80 as it is written 
onto the output file. Both unchanged records from the input file and 
records inserted from the update file are resequenced. 
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Insert Control Statement — inserts all records following it, up to the 
next control statement, into the output file. The foriat of the Insert 
control statement is: 



| ./ I seqno [$ [seqstrt [seqincr]]] | 
i 1 



where : 
seqno 



is the sequence number of the source input record 
following which the insertion is to be made. 



optional delimiter indicating that the inserted records 
are to be sequenced incrementally. 



seqstrt a one- to eight-digit numeric field specifying the 
first decimal number to be used for sequencing the 
inserted records. 



seqincr a one- to eight-digit numeric field specifying the 
decimal increment for sequencing the inserted records. 



All records following the "./ I" statement, up to the next control 
statement, are inserted in the output file following the record 
identified by the "seqno" field. If the NOINC option is specified, each 
inserted record is identified with asterisks (********) in columns 
73-80. If either the IBC or CTL option is specified, the records are 
inserted unchanged in the output file, or they are sequenced according 
to the "seqstrt" and "seqincr" fields, if the dollar sign ($) key is 
specified. 



The default sequence increment, if the dollar sign is included, is 
determined by using one tenth of the least significant, non-zero digit 
in the seqno field, with a maximum of 100. The default seqstrt is 
computed as seqno plus the default seqincr. For example, the control 
statement: 

./ I 2600 $ 2610 

causes the inserted records to be sequenced XXX02610, XXX02620, and so 
forth (NOSEQ8 assumed here) . For the control statement: 

./ I 240000 $ 

the defaulted seqincr is the maximun, 100, and the starting sequence 
number is 240100. SEQ8 is assumed, so the inserted records are 
sequenced 00240100, 00240200, and so forth. 



If either INC or CTL is specified but the dollar sign is not 
included, whatever sequence number appears on the inserted records in 
the update file is included in the output file. 
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Delete Control State ment — deletes one or more records from the source 
file. The format of the Delete control statement is: 



I ./ D seqnol [seqno2] [$] | 

where; 

seqnol is the sequence number identifying the first or only 
record to be deleted. 

seqno2 is the sequence number of the last record to be 
deleted. 

$ is an optional delimiter indicating the end of the 

control fields. 



All records of the input file, beginning at seqnol, are deleted from 
the output file, up to and including the seqno2 record. If the seqno2 
field is omitted, only a single record is deleted. 

Replace Control Statement — replaces one or more input records with 
updated records from the update file. The format of the Replace control 
statement is: 

i 1 

| ./ R seqnol [seqno2] [$ [seqstrt [seqincr]]]| 

i 1 

where: 

seqnol is the sequence number of the first input record to be 
replaced. 

seqno2 is the sequence number of the last record to be 
replaced. 

$ is an optional delimiter key indicating that the 

substituted records are to be sequenced incrementally. 

seqstrt a one- to eight-digit numeric field specifying the 
first decimal number to be used for sequencing the 
substituted records. 

seqincr a one- to eight-digit numeric field specifying the 
decimal increment for sequencing the substituted 
records. 



All records of the input file, beginning with the seqnol record, up 
to and including the seqno2 record, are replaced in the output file by 
the records following the "./ R" statement in the update file, up to the 
next control statement. As with the "./ D" (delete) function, if the 
seqno2 field is omitted, only a single record is replaced, but it may be 
replaced by more than a single inserted record. The "./ R M (replace) 
function is performed as a delete followed by an insert, such that the 
number of statements inserted need not match the number deleted. The 
dollar sign ($) , seqstrt, and seqincr processing is identical to that 
for the insert function. 
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Comment Statements — The format of the Coiment statement is: 

i 1 

| ./ * [comment] | 

i 1 



where: 



indicates that this is a coiment statement, and is to 
be ignored, except that it is copied into the log 
file. 



Summary of InjJUt and Output Files for the UPDATE Command 

The following sections describe the files used and created by the UPDATE 
command, and the placement of the files created. 

INPUT FILES WHEN A SINGLE UPDATE IS TO BE APPLIED: When the CTL option 
is not specified in the UPDATE command, line, only one update is applied 
to the source file. The input files are: 

• The source file, which is to be updated. The filename of this file 
must be specified in the command line. The filetype and filemode 
default to ASSEMBLE and A1, respectively, unless overridden by the 
command line. 

• The update file, whose control statements have been described in the 
preceding section. The filename of this file defaults to the 
filename of the source file, and the filetype and filemode default to 
UPDATE and A1 , respectively. All three may be overridden by the 
command line. 

OUTPUT FILES WHEN A SINGLE UPDATE IS APPLIED: When a single update is 
applied to the source file, the following output files are created: 

• An updated source file is created. "$fn" becomes the name of this 
file, where n fn n is the filename of the original source file, unless 
the REP option is specified. When the REP option is specified, the 
filename of this file becomes "fn". (For exceptions, see the 
"Warning and Error Handling" section that follows.) 

• An update log, showing all transactions and errors, is created. The 
filename of the file is the filename of the original source file, and 
the filetype of this file is UPDLOG. Note, however, that if the 
PRINT option is specified with the command line, then the update log 
is printed directly on the virtual spooled printer, and no disk file 
is created. 

INPUT FILES WHEN MULTILEVEL UPDATES ARE APPLIED: When the CTL option is 
specified on the command line, multilevel updates are applied to the 
source file. In this case, the following files are input to the UPDATE 
command: 

• A source file, specified in exactly the same way as the source file 
for a single update. 
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• A control file that controls what updates are applied, and the order 
in which they are to be applied. The filename of this file defaults 
to the filename of the source file, and the filetype and filemode 
default to CMTRL and A1, respectively. All three may be overridden 
by the command line. This file contains, in its control statements, 
pointers to update files, PTF files, and auxiliary files (these are 
described in "The CTL Option" section) . 

• one or more update files, as specified by the control file. The 
filename of these files is the same as the filename of the source 
file. The filetype of these files is "UPDTxxxx". 

• Auxiliary files, as specified by the control file. The filename of 
these files is the same as the filename of the source file. The 
filetype of these files is "AUXxxxx". The filetype can be specified 
as either •AUXnnnn* or 'nnnn AUX*. If you use the second form, the 
first three characters may not be •AOX 1 . The auxiliary files contain 
additional control statements pointing to PTF files. The format of 
the auxiliary files is described in a later section, "The CTL 
Option." 

• PTF files, as specified by either the control file or the auxiliary 
files. The filename of these files is the same as the filename of 
the source file. The filetype is specified in full by the control 
file or the auxiliary file. In format, these files are identical to 
ordinary update files. 

OUTPUT FILES KHEJ HUITIIBVBL UPDATES ARE APPLIED; When the CTL option is 
specified, the following output files are created by the UPDATE command: 

• An updated source file, as in the case of a single update. 

• An update log, as in the case of a single update. 

• An UPDATES file. This file has the filename of the original source 
file, and a filetype of UPDATES. It contains summary information 
about which updates were applied to the file, and is intended to be 
concatenated onto the assembly text deck for documentation and 
information purposes. 

• Although not a disk file, additional "output" is produced in the form 
of lines placed in the terminal read stack, for interrogation by an 
EXEC file which may have invoked the UPDATE command. These lines are 
placed there only if the STK option is specified. 

DISK MODE OF OUTPUT FILES; If there are several read/write disks 
accessed when the UPDATE command is invoked, the following steps are 
taken to determine the disk upon which the output files are to be placed 
(the search stops as soon as one of the following steps is successful) : 

• If the disk on which the original source file resides is read/write, 
then the output files are placed on that disk. 

• If that disk is a read-only extension of a read/write disk, then the 
output files are placed on that particular read/write disk. 

• Otherwise, the output files are place on the primary read/write disk 
(the A-disk) . 
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The CTL Option 

If the HOCTL option is specified or defaulted, UPDATE processes one 
input file and one update file to produce an updated source output file 
and an update log file containing a record of what changes were Bade. 
This mode of operation is suitable for testing modif ications prior to 
incorporating thei in the base source code, providing that only one set 
of changes has to be tested at a tine. If, for any reason, lore than 
one set of changes is outstanding against a single source input file, 
the difficulties in Managing that base code can Multiply very rapidly. 
For this reason, UPDATE provides the CTL option, which has a Multilevel 
update control and Management scheme developed for updating VH/370 
distributed source code, and May be used wherever its advantages are 
felt. 

The Major components of the Multilevel update scheme are: 

• A set of base source code which is not permanently changed. 

• A set of update files for each source file that Must be applied in a 
specific order. 

• One or More CHTRL files that describe the order or priority of 
updates to be applied to each source file. 

• Optionally, one or More auxiliary control files, each pertaining to a 
specific source file. 

An integral part of the Multilevel update scheme is a naming 
convention for the update files theMselves, and for any TEXT files 
produced by asseMbling or coMpiling the updated output files. In normal 
usage, any update file has the filename of the source file to which it 
applies and the filetype of UPDATE. When the CTL option is used to 
invoke the Multilevel update controls, the filenaMe usage becomes a 
reguireMent, such that the update files Must have the filename of the 
source file to which they apply, but the filetypes are modified to 
distinguish between separate update levels. The filetype for an update 
file is constructed from UPDT plus a one- to four-character update 
identifier. For example, if the command 

UPDATE DHSUPD ASSEMBLE A1 XU CHTRL A1 (CTL 

is issued, the source file is DHSUPD ASSEMBLE A1 and the control file is 
X4 CNTRL A1. Assume that the control file contains three update files, 
named "DHSUPD UPDT750", "DHSUPD UPDTX4", and "DHSUPD UPDT009." The 
CNTRL file specifies which update files are to be applied to the source 
file and in what order they are to be applied, on the basis of the 
update identifier. Another identification parameter, the update level 
identifier, is used when naming a TEXT file produced from the updated 
source file. The update level identifier is specified by the CNTRL file 
and is associated with a specific update identifier, also in the CNTRL 
file. For example, a file named X4 CNTRL, to apply the above mentioned 
updates to DHSUPD ASSEHBLE, might appear as follows: 

00D HACS DHSLIB SYSLIB 
X4D UPDTXU 
75X UPDT750 
009X UPDT009 
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This control file applies the updates DBSUPD UPDT009, DBSUPD UPDT750, 
and DBSUPD UPDTX4, in that order, to the file DBSDPD ASSEMBLE. The 
updates are applied in reverse order as they appear in the CHTRL file, 
that is, the lowest level of update is at the bottom of the file, and 
the highest level update is at the top. As the CHTRL file and update 
files are processed, the UPDATE coinand displays the following Message 
at the terminal: 

DMS0PD178I UPDATING [»fn ft fm» ] WITH »fn ft f ■ • 

for each update file which is applied to the source input during the 
multilevel update; the bracketed expression is displayed only for the 
first update. 



In the above example, the fields X4D, 75X, and 009X are the update 
level identifiers, associated with the UPDTX4, UPDT750, and UPDT009 
update identifiers, respectively. According to the naming convention 
for VB/370 TEXT files, the result of assembling the updated SDBSUPD 
ASSEBBLE file would be named DBSUPD TXTX4D, where the X4D is the update 
level identifier of the highest-level update applied. The TXT portion 
of the filetype indicates that this is a TEXT file, but allows up to a 
five-character update level identifier. 



The STK/NOSTK Options 

The STK option is provided for use with the multilevel update invoked 
via the CTL option, primarily for communication with CBS EXEC procedures 
which invoke UPDATE. If the CTL and STK options are specified, UPDATE 
places two lines of data in the CBS terminal read stack, as follows: 

first line = * update level identifier 

second line = * library list from ' BACS 1 record 



These lines are placed in the terminal read stack via the CBS ATTN 
function, and are available to an invoking EXEC procedure via the EXEC 
control words &READ ARGS or &READ VARS. The first line, the update 
level identifier, is the level identifier of the highest level update 
applied; this is the TEXT file filetype-modifier used by the VB/370 
update procedures. The second line consists of the list of libraries 
specified on the BACS record in the CNTRL file. The library search 
order for an assembly or compilation can be established by issuing the 
GLOBAL command using the library list returned. 



If the NOSTK option is used with the multilevel update, no data is 
made available to external procedures and the update level identifier 
has no meaning. 
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Example of Mul tileve l Update 

If the command 

update proga assemble * proga cntrl * (ctl stk) 
is issued and the contents of the PROGA CNTRL file are 



* THIS IS AN EXAMPLE OF A CONTROL FILE 
00D MACS HYLIB SYSLIB 

* FIX FOR SAVING ALL REGISTERS 
00A UPDTLVL4 

PTF A7300DHS 

* AUX FILE CONTAINING UPDATES FOR B1 FEATURE 
00B AUXLVL3 



and the contents of the PROGA AUXLVL3 file are : 

i 1 

| * PTF A2330DHS CONTAINS FUNCTIONAL CODE FOR B1 | 

| PTF A2330DMS | 

| * PTF A0915DHS CONTAINS ERROR MESSAGES FOR B1 | 

| PTF A0915DMS | 

i i 



The files listed below are used to update PROGA ASSEMBLE in the order 
indicated. 

Filename Filetype 

PROGA*" A0915DMS 

PROGA A2330DMS 

PROGA A7300DMS 

PROGA UPDTLVL4 



The resultant output file $PROGA ASSEMBLE contains the updates from 
the four files listed. In addition, two lines are placed in front of 
the CHS terminal read stack: 

* 00A 

* HYLIB SYSLIB 



If the UPDATE command shown was issued from an EXEC procedure and 
followed by the EXEC commands: 

&READ VARS 611 &I2 
BREAD VARS &I3 614 SI5 

then 

611 « * 

612 = 00A 

613 = * 

614 = HYLIB 

615 = SYSLIB 

In this example, the UPDATE command was entered from the terminal and 
the stacked lines are ignored by CHS. 
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laming and Error Handling 

The UPDATE command detects a number of invalid requests, and decides 
whether they should be treated as warning situations or as errors. The 
following is a general description of the handling of these situations, 
and the return codes associated with each. 



SEQUENCING AND UPDATE CONTROL CARD ERRORS: These errors are treated as 
"warning situations." That is, a warning message is generated, and 
processing continues. The warning messages are printed in the update 
log, and are displayed on the terminal unless the NOTERH option is 
specified in the command line. The errors are: 

• Input sequencing errors (return code = 4) . The input source file 
contains sequence errors (sequence numbers in nonascending order) • 

• Output sequencing errors (return code = 8) . The updating procedure 
introduces new seguencing errors into the output source file. 

• Invalid update control statements (return code = 12) . The update 
file contains invalid control statements. Erroneous statements in 
control files cause the update procedure to terminate. 

If more than one such error is detected, the UPDATE command returns 
the highest return code (4, 8, or 12) encountered. 

If any such error is detected, the REP option, if specified, is 
ignored, and the update source file retains the filename "$fn", as if 
MOREP was in effect. 



OTHER ERR ORS ; Other errors are invalid control file statements, invalid 
file formats, and disk input /output errors. The UPDATE command 
processing is terminated as soon as the error is detected. The return 
code is always 20 or greater. 

If any such error is detected, the update file is left with the 
filename UPDATE and the filetype CHSUT1, so that you may examine or 
otherwise make use of it. This file must be erased before the UPDATE 
command can be invoked again. 



Responses 

FILE 'fn ft fm, 1 REC in = update control statement 

This message is displayed when the TERN option is specified and an 
error is detected in an update file. It identifies the file and 
record number where the error is found. 

DHSUPD177I WARNING MESSAGES ISSUED (SEVERITI=nn) . [»REP« OPTION 
IGNORED. ] 

Warning messages were issued during the updating process. The 
severity shown in the error message in the • nn' field is the 
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UPDATE 

highest of the return codes associated with the warning Messages 
which were generated during the updating process. 

The warning return codes have the following meanings: 

RC = 4; Seguence errors were detected in the original source file 
being updated. 

RC = 8; Seguence errors which did not previously exist in the 
source file being updated were introduced in the output file 
during the updating process. 

RC = 12; Any other nonfatal error detected during the updating 
process has a return code of 12. Such errors include invalid 
update file control statements, and missing PTF files. 

The severity value is passed back as the return code from the 
UPDATE command. In addition, if the REP option is specified in 
the command line, then it is ignored, and the updated source file 
has the fileid "$fn1 ft1", as if the REP option was not 
specified. 

DMSUPD178I UPDATIHG [ «fn ft fm» ] WITH • f n ft fm« 

The specified update file is being applied to the source file. 
This message appears only if the CTL option is specified in the 
command line. The updating process continues. 



Other Messages and Return Codes 

DMSUPD001E NO FILENAME SPECIFIED RC=4 

DMSUPD002E FILE • f n ft fm» HOT FOUND RC=28 

DMSUPD003E INVALID OPTION • option 1 RC=24 

DMSUPD007E FILE «fn ft fm» IS HOT FIXED, 80 CHAR. RECORDS RC=32 

DMSUPD010W PREMATURE EOF OF FILE »fn ft fm« — SEQ NUMBER • • NOT 

FOUND RC=12 
DMSUPD024E FILE 'UPDATE CMSUT1 fm» ALREADY EXISTS RC=24 
DMSUPD037E DISK «A« IS RBAD/ONLY RC=36 
DMSUPD048E IHVALID MODE •mode 1 RC=24 
DMSUPD065E •option 1 OPTIOH SPECIFIED TWICE RC=24 
DMSUPD066E 'option 1 AHD • option* ARE COHFLICTIHG OPTIONS RC=24 
DMSUPD069E DISK *A* NOT ACCESSED RC-36 
DMSUPD070E INVALID PARAMETER »param» RC=24 

DMSUPD104S ERROR «nn» READING FILE • f n ft fm» FROM DISK RC=100 
DMSUPD105S ERROR • nn» WRITING FILE »fn ft f m • ON DISK RC=100 
DMSUPD174W SEQUENCE ERROR INTRODUCED IN OUTPUT FILE: • • TO 

• • RC=8 

DMSUPD176W SEQUEHCIHG OVERFLOW FOLLOWIHG SEQ HUMBER* • RC = 8 

DMSUPD179E MISSIHG OR DUPLICATE •MACS' CARD IH COHTROL FILE • f n ft fm» 

RC=32 
DMSUPD180W MISSIHG PTF FILE «fn ft fm» RC=12 
DMSUPD181E NO UPDATE FILES WERE FOUHD RC=40 
DMSUPD182W SEQUEHCE IHCREMEHT IS ZERO RC=8 
DMSUPD183E IHVALID { COHTROL| AUX ) FILE COHTROL CARD RC=32 
DMSUPD184W »./S • HOT FIRST CARD IH IHPUT FILE — IGHORED RC=12 

DMSUPD185H IHVALID CHAR IH SEQUEHCE FIELD • • RC=12 

DHSUPD186W SEQUEHCE HUMBER • * HOT FOUHD RC=12 

DMSUPD187E OPTIOH »STK» IHVALID WITHOUT «CTL» RC=24 

DMSUPD207W IHVALID UPDATE FILE COHTROL CARD RC=4 

DMSUPD210W IHPUT FILE SEQUEHCE ERROR: • • TO • • RC=4 
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IMMEDIATE COMMANDS 

IMMEDIATE COMMANDS 

An IMMEDIATE command is issued after an Attention interrupt is given to 
CMS by pressing the Attention key (or its eguivalent) . Such commands 
are processed immediately upon entry from the terminal or on being 
•stacked" by an EXEC procedure. Any program execution in progress is 
i suspended until the immediate command is Processed* The commands are HB 
| (halt batch execution) , HO (halt SVC tracing) , HT (halt typing) , HX 
(halt execution) , RO (resume tracing) , RT (resume typing) , and SO 
(suspend tracing temporarily) . 



I HB 

| Use the HB command to stop the execution of a CMS Batch virtual machine 

| at the end of the current job. If the virtual machine is running in 

I disconnect mode, it must be reconnected. Press the Attention Key to stop 

| program execution and enter the command. CMS sets a flag such that at 

| the end of the current job, the batch processor generates accounting 

| information for the current job and then logs out the CMS Batch virtual 

| machine. 



I ( HB | | 

| i 1 

I Responses 
| None. 

HO 

Ose the HO command during the execution of a command or one of your 
programs to stop the recording of trace information. In order for the HO 
command to be recognized, it must be entered after you stop program 
execution by an Attention interrupt. Program execution continues to its 
normal completion, and all recorded trace information is spooled to the 
printer. The format of the HO command is: 



i 1 

I HO | | 

i i 



Responses 
None. 
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IMMEDIATE COMMANDS 



HT 



Use the HT command to suppress all terminal output generated by any CMS 
command or your program that is currently executing. In order for the 
HT command to be recognized when entered, an Attention interrupt must be 
simulated by pressing the Attention key or its eguivalent. Program 
execution continues. With typewriter terminals, the Attention key 
unlocks the keyboard to accept your HT command. With display terminals, 
you enter the HT command in the input area and then press the Enter 
key. When the Ready oessage is displayed, normal terminal output 
resumes. The format of the HT command is: 



i 1 

I HT | I 

i i 



Responses 



None. 



HX 

Use the HX command to stop the execution of any CMS command or one of 

your programs under CMS, close any open files or I/O devices, and return 

to the CMS command environment. In order for the HX command to be 

recognized, it must be issued after you stop program execution by an 

Attention interrupt. The HX command is executed when the next SVC or 

I/O interrupt occurs. All terminal output generated before HX is 

executed is displayed before the command is executed. The format of the 
HX command is: 



| HX 
i 



Responses 



None. 
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IMMEDIATE COMMANDS 



HO 

Use the RO command, during the execution of a command or one of your 
programs, to resume the recording of trace information that was 
temporarily suspended by the SO command. In order for the RO command to 
be recognized, it must be entered after you stop program execution with 
an Attenion interrupt- Program execution continues to its normal 
completion, and all recorded trace information is spooled to the 
printer. The format of the RO command is: 



RO | | 

, i 



Responses 



None. 



RT 

Use the RT command to restore terminal displaying from an executing CMS 
command or one of your programs that was previously suppressed by the HT 
command. In order for the RT command to be recognized when entered, an 
Attention interrupt must be simulated by pressing the Attention key or 
it eguivalent. Program execution continues, and displaying continues 
from the current point of execution in the program. Any console output 
that is generated after the HT command is issued and up to the time the 
RT command is issued is lost. Execution continues to normal program 
completion. The format of the RT command is: 



i 

| RT 
i 



Responses 



None. 
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SO 

Use the SO command during the execution of a command or one of your 
programs to temporarily suspend the recording of trace information. 
Tracing resumes if you issue the BO command at a later time. In order 
for the SC command to be recognized, it must be entered after you stop 
program execution with an Attention interrupt. Program execution 
continues to its normal completion and all recorded trace information is 
spooled to the printer. The format of the SO command is: 



• 1 

I SO | I 

I I 



Re sp onses 



None. 
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CP Command Privilege Classes 

The CP conaands are divided into eight privilege classes, each class 
representing a different type of user. Bach user is assigned, as part 
of his entry in the VH/370 directory, one or aore privilege classes. 
Figure 33 shows the function of each class. The footnotes following the 
privilege class indicate where the coaaands of that particular privilege 
class are described. Figure 34 shows which conands (and which 
operands, if the coaaand varies for different privilege classes) are 
associated with each class. Only class G coaaands and class Any 
coaaands are included in this publication. 
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Class 



A* 



B* 

C*,« 

D* 
G* 



Any 



1 4 



User and Function 



Priiary System Operator; The class A user controls the 
VM/370 system. Class A is assigned to the user at the VM/370 
system console at IPL tine. The priiary system operator is 
responsible for the availability of the VM/370 system and its 
communication lines and resources. In addition, the class A 
user controls system accounting, broadcast messages, virtual 
machine performance options and other command operands that 
affect the overall performance of VM/370. 

Note: The class A system operator who is automatically logged 
on during CP initialization is designated as the Primary 
System Operator. 

§!§£§■ Resource Operator: The class B user controls all the 
real resources of the VM/370 system, except those controlled 
by the primary system operator and spooling operator. 

System Programmer: The class C user updates certain 
functions of the VM/370 system. 

§£22li53 Operator: The class D user controls spool data 
files and specific functions of the system's unit record 
eguipment. 

System Analyst: The class E user examines and saves certain 
data in the VM/370 storage area. 

Service Representative : The class F user obtains and 
examines in detail, certain data about input and output 
devices connected to the VM/370 system. 

General User: The class G user controls functions associated 
with the execution of his virtual machine. 

Any. User: The class Any user has limited use of VM/370 to 
gain initial access to the VM/370 system. 

Reserved for IBM use. 



1 Described in the VM/370: Operator's Guid e. 

^Described in the VM/370: System Programm er's Guide. 

3 Described in the VM/370: OLTSEP and Error Recording Guide. 

♦Described in this publication. 



Figure 33. CP Privilege Class Descriptions 
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r 

| Class 


Commands 


Operands | 


| Class 


Commands 


■ 

Operands | 


I any 


#CP 








| SHUTDOWN | 
VARY | 




CP 






QUERY 


ALL | 




DIAL 








DASD | 




DISCQNN 








DUMP j 




LOGOFF 








GRAF | 




LOGON 








LINES | 




MESSAGE 








LOGMSG | 




SLEEP 








NAMES j 
raddr | 


i a 


ACNT 

DISABLE 

ENABLE 

FORCE 

HALT 

LOCK 








SPOOL | 
STORAGE | 
SYSTEM | 
TAPES | 
TDSK | 
UR | 




MESSAGE 


ALL | 






userid | 




MONITOR 


DISPLAY | 






USERS | 






ENABLE | 




SET 


DUMP | 






INTERVAL j 






LOGMSG | 






START | 




VARY 








STOP | 




WARNING 






NETWORK 


DISABLE | 












DISPLAY | 


1 c 


QUERY 


LOGMSG | 






DUMP | 






NAMES | 






ENABLE I 






userid | 






HALT J 






USERS | 






LOAD | 




STCP 




1 1 




POLLDLAY | 












QUERY | 


1 D 


BACKSPAC 








SHUTDOWN | 




CHANGE 








VARY | 




DRAIN 






QUERY 


LOGMSG | 
NAMES | 
PRIORITY | 
SASSIST ! 
user id | 
USERS | 




FLUSH 

FREE 

HOLD 

LOADBUF 

ORDER 

PURGE 




1 1 


SET 


FAVORED | 
PRIORITY | 
RESERVE | 
SASSIST | 




QUERY 


FILES | 
HOLD | 
LOGMSG | 
NAMES | 




SHUTDOWN 








PRINTER | 




UNLOCK 








PUNCH | 




WARNING 








READER | 
UR | 


1 B 


ATTACH 








userid | 




ATTACH 


CHANNEL | 






USERS | 




DETACH 






REPEAT 






DETACH 


CHANNEL | 




SPACE 






DISABLE 






START 






ENABLE 






TRANSFER 






MESSAGE 


ALL | 










NETWORK 


DISABLE | 
DISPLAY | 


1 E 


DCP 
DMCP 








DUMP | | 




INDICATE 


I/O I 






ENABLE | | 






LOAD | 






LOAD | | 






PAGING | 


1 1 




POLLDLAY | | 






QUEUES | 


■ 




QUERY | | 

■ 


■ 




USER | 


| Figure 34. 
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)f 2) 
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1 




_ ., r _ _ 


_ ... — _ , 


| Class 


Commands 


Operands | | Class | Commands 


Operands | 




LOCATE 




LINKS | 




MONITOR 


DISPLAY | | | 


LOGMSG | 






ENABLE | | | 


NAMES | 






INTERVAL Ml | 


PFnn | 






START | | | 


PRINTER | 






STOP | | | 


PUNCH | 




QUERY 


LOGMSG | | | 


READER | 






NAMES | | | 


SET | 






PAGING | | | 


TERMINAL | 






PRIORITY | | | 


TIME | 






SASSIST | | | 


userid | 






userid | | | 


USERS | 






USERS | | | 


VIRTUAL | 




SAVESYS 


| | | READY 




1 F 


NETWORK 


TRACE | | | REQUEST 






QUERY 


LOGMSG | | | RESET 
NAMES | | | REWIND 








userid | | | SET 


ACNT | 






USERS | | | 


ASSIST | 




SET 


RECORD Ml | 


ECMODE | 






MODE | | | 


EMSG | 
IMSG | 


1 G 


ADSTOP 


II 1 1 


ISAM | 




ATTN 




LINEDIT | 




BEGIN 




MSG | 




CHANGE 




NOTRANS | 




CLOSE 


III 1 


PAGEX | 




COUPLE 




PFnn | 




DEFINE 


III 1 


PFnn COPY | 




DETACH 




PFnn TAB | 




DISPLAY 




RUN | 




DUMP 




TIMER | 




ECHO 




WNG | 




EXTERNAL 


| | | SPOOL 




1 1 
1 1 


INDICATE 


LOAD | | | STORE 
USER || - | SYSTEM 






IPL 


1 1 1 TAG 


DEV j 




LINK 




FILE | 




LCADVFCB 




QUERY | 




NOTREADY 


| | | TERMINAL 






ORDER 


| | | TRACE 






PURGE 


| | | TRANSFER 






QUERY 


CHANNELS | | | 
FILES | j j 




L ... _ _ 




. .,,..,_ ..,_,.., j i . 


• 


Figure 34 
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C1P Command Summary 



This section contains descriptions of the commands acceptable in the 
control program environment. Figure 35 presents an alphabetical list of 
the commands, the privilege classes which may execute the command, and a 
brief statement about the use of each command. 



Command 



* 
#CP 

ACNT 

ADSTOP 

ATTACH 

ATTN 

BACKSPAC 

BEGIN 

CHANGE 
CLOSE 



COUPLE 


G 


CP 


any 


DCP 


E 


DEFINE 


G 


DETACH 


B 
B 
B 
G 



DIAL 



DISABLE 



Privilege 
Class 



any 
any 



D.G 



any 



A,B 



Osage 



Annotate the console sheet. 

Execute a CP command while remaining in the 
virtual machine environment. 

Create accounting records for logged on users 
and reset accounting data. 

Halt execution at a specific virtual machine 
instruction address. 

Attach a real device to a virtual machine. 
Attach a DASD device for CP control. 
Dedicate all devices on a particular channel 
to a virtual machine. 

Make an attention interrupt pending for the 
virtual machine console. 

Restart or reposition the output of a unit 
record spooling device. 

Continue or resume execution of the virtual 
machine at either a specific storage location 
or at the address in the current PSW. 

Alter one or more attributes of a closed spool 
file. 

Terminate spooling operations on a virtual card 
reader, punch, printer, or console. 

Connect channel-to-channel adapters. 

Ignored. 

Display real storage at terminal. 

Reconfigure your virtual machine. 

Disconnect a real device from a virtual machine. 

Detach a DASD device from CP. 

Detach a channel from a specific user. 

Detach a virtual device from a virtual machine. 

Connect a terminal or display device to the 
virtual machine's virtual communication line. 

Disable 2701/2702/2703 and 3270 communication 
lines. 



Figure 35. CP Command Summary (Part 1 of H) 
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Command 


Privilege 
Class 


DISCONN 


any 


DISPLAY 


G 


DMCP 


E 



DRAIN 
DUMP 

ECHO 

ENABLE 
EXTERNAL 

FLUSH 

FORCE 

FREE 

HALT 

HOLD 

INDICATE 
IPL 
LINK 

LOADBUF 
LOADVFCB 

LOCATE 
LOCK 

LOGOFF 

LOGON 

MESSAGE 



A,B 
G 



A 

D 
A 

D 

E,G 
G 
G 

D 
G 

E 
A 

any 
any 
A,B,any 



Usage 



Disconnect your terainal from your virtual 
■achine. 

Display virtual storage on your terainal. 

Dump the specified real storage location on your 
virtual printer. 

Halt operations of specified spool devices upon 
completion of current operation. 

Print on virtual printer: virtual PSI, general 
registers, floating— point registers, storage 
keys, and contents of specified virtual 
storage locations. 

Test terminal hardware by redisplaying data 
entered at the terminal. 

Enable communication lines. 

Simulate an external interrupt for a virtual 
machine and return control to that machine. 

Cancel the current file being printed or punched 
on a specific real unit record device. 

Cause logoff of a specific user. 

Remove spool HOLD status. 

Terminate the active channel program on 
specified real device. 

Defer real spooled output of a particular user. 

Indicate resource utilization and contention. 

Simulate IPL for a virtual machine. 

Provide access to a specific DASD device by a 
virtual machine. 

Load real UCS/UCSB or FCB printer buffers. 

Load virtual forms control buffer for a virtual 
3211 printer. 

Find CP control blocks. 

Bring virtual pages into real storage and lock 
them; thus excluding them from future paging. 

Disable access to CP. 

Provide access to CP. 

Transmit messages to other users. 



Figure 35. CP Command Summary (Part 2 of 4) 
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Command 



MONITOR 

»t nmonnv 
nuKunn 

HOTBEADY 

ORDER 

PURGE 
QUERY 

READY 

REPEAT 

REQUEST 

RESET 

REWIND 

SAVESYS 

SET 



SHUTDOWN 


A 


SLEEP 


any 


SPACE 


D 


SPOOL 


G 



START 

STCP 
STORE 



Privilege 
Class 



A,E 



n ,d ,c 



D,G 



D,G 



A,B,C,D, 
E,F,G 



A,B,F,G 



Usage 



Trace events of the real machine and record 
system performance data. 

Lead, dump, trace and control the operation of 
the 3704/3705 control program. 

Simulate "not ready" for a device to a virtual 
machine . 

Rearrange closed spool files in a specific 
order. 

Remove closed spool file from system. 

Reguest information about machine configuration 
and system status. 

Simulate device end interrupt for a virtual 
device. 

Repeat (a specified number of times) printing or 
punching of a specific real spool output file. 

Make an attention interrupt pending for the 
virtual machine console. 

Clear and reset all pending interrupts for a 
specified virtual device and reset all error 
conditions. 

Rewind (to load point) a tape and ready a tape 
unit. 

Save virtual machine storage contents, 
registers,- and PSW* 

Operator — establish system parameters. 
User — control various functions within the 
virtual machine. 

Terminate all VM/370 functions and checkpoint CP 
system for warm start. 

Place virtual machine in dormant state. 

Force single spacing on printer. 

Alter spooling control options; direct a file to 
another virtual machine or to a remote 
location via the RSCS virtual machine. 

Start spooling device after draining or changing 
output classes. 

Change the contents of real storage. 

Alter specified virtual storage and registers. 



Figure 35. CF Command Summary (Part 3 of 4) 
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Command 


Privilege 
Class 


Usage 


SYSTEM 


G 




Simulates RESET, CLEAR STORAGE and RESTART 
buttons on a real system console. 


TAG 


G 




Specify variable information to be associated 
with a spool file or output unit record 
device. 

Interrogate the current TAG text setting of a 
given spool file or output unit record device. 


TERMINAL 


G 




Define or redefine the input and attention 
handling characteristics of your virtual 
console. 


TRACE 


G 




Trace specified virtual machine activity at your 
terminal, spooled printer, or both. 


TRANSFER 


D, 


G 


Transfer input files to or get input files from 
a specified user's virtual card reader. 


UNLOCK 


A 




Unlock previously locked page frames. 


VARY 


B 




Mark a device unavailable or available. 


WARNING 


A, 


B 


Transmit a high priority message to a specified 
user or to all users. 



Figure 35. CP Command Summary (Part 4 of 4) 
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Privilege Class ; Any 

Use * to annotate the terminal console sheet or terminal display screen 
data with a comment. This commentary also appears in the virtual 
console spool file (if the console spooling function is invoked for the 
virtual machine) . The format of the * (comment) command is: 



| * | anycomment 

i 



Responses 



Hone. 
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#CP 

#CP 

Privilege Class; Any 

Use the #CP command to execute a CP command while in a virtual console 
read environment without first signalling attention to get to the CP 
environment. The format of the #CP command is: 



i 

| #CP I [commandlinel [#commandline2 #...]] 
i 



where: 

commandline specifies the name, operands, and options for the CP 
command or commands you want to issue. You must precede the 
first commandline with at least one blank. 

The pound sign (#) shown in the format above represents the logical 
line end symbol currently in effect for your virtual machine. If you 
have redefined the logical line end symbol, #CP is an invalid command; 
you must substitute your line end symbol for the pound sign when using 
this command. 

Osage: 

For the command to operate, the following conditions must be met: 

• The virtual machine must be running with SET LIHEDIT ON (a default) . 

• The first three characters of the edited line must be #CP (upper or 
lowercase) with the M #" representing the logical line end character 
currently defined. 

• At least one blank must separate the #CP from any command line. Do 
not use attention interruption in any part of the line or to enter 
the line. 

You can enter multiple command lines as operands of the #CP command, 
but you must separate each command line by the logical line end (#) 
character. If you enter only #CP with no operands, the virtual machine 
enters the CP environment. CP cancels the virtual machine's console 
READ by returning a unit exception status for the virtual console. The 
virtual operating system then reissues the console BEAD to allow you to 
key in the appropriate response to a previous message from that 
machine's operating system. 
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The following examples show several ways to use #CP: 



#CP 



r — 

| Command 






• 

System Action | 


| #CP 






Tour virtual machine enters | 
| CP environment. j 


| *CP query files 






| QUERY command executed. j 


j #CP query filesiquer] 


r users 


| Two separate QUERY commands j 
executed. | 


| data enteredMCP msg 
I available 


op 


is tape 


"Data entered" is ignored. You | 

| send a message to the | 

operator. j 


| #CP data entered 






You enter CP environment and j 
CP interprets "data entered" | 
as an invalid operand. | 


| data enteredMCP 






"Data entered" is ignored. You j 
enter CP environment. j 


j #CP query filesldata 


entered 


QUERY command is not executed; j 
console input (data entered) | 
passes to the virtual machine. | 



Responses: 

If you enter #CP without a commandline, you receive this message: 

CP 

If you enter fCP with commandlines, you receive the responses 
appropriate to the individual commands you entered. 
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ADSTOP 

ADSTOP 

Privilege Class; G 

Use the ADSTOP coaaand to halt execution at a virtual instruction 
address. Execution halts when the instruction at the specified address 
is the next instruction to be executed. 

When execution halts, the CP coanand aode is entered and a Message is 
displayed. At this point, you aay invoke other CP debugging commands. 
To resume operation of the virtual aachine, issue the BEGIN coaaand. 
Once an ADSTOP location is set, it aay be reaoved by one of the 
following: 



• Beaching the virtual storage location specified in the ADSTOP coaaand 

• Performing a virtual IPL or SYSTEM BESET 

• Issuing the ADSTOP OFF coaaand 

• Specifying a different location with a new ADSTOP hexloc coaaand 



The foraat of the ADSTOP coaaand is: 



i — " ■' — ~ -■■ ' " - •- ~'i 

| ADSTOP | ( hexloc \ I 

I I I OFF J | 



where: 

hexloc is the hexadecimal representation of the virtual instruction 
address where execution is to be halted. The specified 
address cannot be in a storage segaent shared with other 
users, since the ADSTOP function modifies storage. 

OFF cancels any previous ADSTOP setting. 



Botes: 

1. Since the ADSTOP function aodifies storage (by placing a CP SVC 
X*B3* at the specified location) your prograa should not exaaine 
the two bytes at the instruction address. CP does not verify that 
the location specified contains a valid CPU instruction. 

2. Address stops aay not be set in an OS/VS or DOS/VS virtual 
aachine's virtual storage; address stops aay only be set in the 
virtual eguals real partitions or regions of those virtual 
aachines. 
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1DST0P 

3. If the SVC handling portion of the virtual machine assist feature 
is enabled on your virtual Machine, CP turns it off when an address 
stop is set. After the address stop is removed, CP returns the 
assist feature SVC handling to its previous status. 



Response 

ADSTOP AT xxxxxx 

The instruction whose address is xxxxxx is the next instruction 
scheduled for execution. The virtual machine is in a stopped 
state. Any CP command (including an ADSTOP command to set the next 
address stop) can be issued. Enter the CP command BEGIN to resume 
execution at the instruction location xxxxxx, or at any other 
location desired. 
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ATTN 

ATTN 

Privilege Class: G 

Dse the ATTN command to make an "attention" interrupt pending at your 
virtual console. The format of the ATTN command is: 



i 1 

| ATTN | I 

• I 



The BEQUEST command performs the same function as ATTN and the two 
commands can be used interchangeably. 

The BEGIN command is not required after you issue ATTN. 



Responses 



None. 
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BEGIN 



BEGIN 



Privilege Class: G 



Use the BEGIN command to continue or resume execution in the virtual 
machine at either a specified storage location or the location pointed 
to be the virtual machined current PSH. The format of the BEGIN 
command is: 



| Begin | [hexloc] 

i 



where: 
hexloc 



is the hexadecimal storage location where execution is to 
begin, when BEGIN is issued without hexloc, execution begins 
at the storage address pointed to by the current virtual 
machine PSW. Unless the PSW has been altered since the CP 
command mode was given control, the location stored in the PSH 
is the location where the virtual machine stopped. 



Mhen BEGIN is issued with a storage location specified, 
execution begins at the specified storage location. The 
specified address replaces the instruction address in the PSW, 
then the PSW is loaded. 



Responses 



None. The virtual machine begins execution. 
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CHANGE 



CHANGE 



Privilege Class: G 



Use the CHANGE command to alter one or more of the external attributes 
of a closed spool file or files. Issue the QUERY command to determine 
the current attributes of the file. In order to change an output file, 
the file must have been closed but not yet selected for printing or 
punching. An input (READER) file can be changed at any time before it 
is opened, that is, before the first read is issued for the file. The 
format of the CHANGE command is: 



CHange | / Reader ( CLass d 
Printer ) spoolid 
PUnch (ALL 



CLass c2 
COpy nn 

r t 

I HOld | 
|NOHold| 

L J 

DIst distcode 



r 
INAme 



|fn [ft]) 
\ dsname/ 



l One of these options must be chosen; however, more than one may be 
specified and they may be combined in any order. This is contrary to 
the notation normally used in this publication. 



where: 

READER 
RDR 

PRINTER 
PRT 

PUNCH 
PCH 

CLASS C1 

spoolid 

ALL 

CLASS C2 
COPY nn 



HOLD 



changes the reader spool file. 

changes the printer spool file. 

changes the punch spool file. 

designates an existing class. The class, d, is a 
one-character alphameric field from A to Z or from 0-9. Refer 
to the VM/370: Operator's Guide for a detailed description of 
spool classes. 

is the spoolid number of the file that is to be changed. Each 
spool file has a unique spoolid. 

changes all your spool files. 

changes the spool class of the file to c2. 

specifies the number of copies of the file to be spooled to 
the virtual output device. This option is valid for printer 
and punch files only. The value of nn (number of copies) must 
be a number from 1 through 99. For nn less than 10, the 
leading zero is optional. 

prevents the file from being printed, punched, or read until 
it is released. The file is released when the CHANGE command 
is issued with the NOHOLD operand specified. 
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CHANGE 



HOHOLD 



releases the specified file from user HOLD status. 



DIST distcode 

changes the distribution code specified in the VM/370 
directory to the distcode specified on the command line, for 
the specified file only. The distribution code appears on the 
output separators of the printer and punch output; it has no 
effect on reader files. 

NAME fn [ft] 

assigns identification to the spool file in the CMS format 
filename and filetype. The field, fn, is a one- to 
eight-character alphameric filename assigned to the file for 
identification. The field, ft, is a one- to eight-character 
alphameric filetype assigned to the file for identification. 
If ft is not specified, the filetype is set to blanks. 

NAME dsname 

assigns identification to the spool file in a non-CHS format. 
The field, dsname, is a 1- to 24-character field suitable for 
specifying OS or DOS files [for example, STS1.SYSLIB.HTMAC]. 



Response 



fnnnn ) 
t HO / 



FILES CHANGED 



This is the response when you issue the CHANGE command. This is an 
indication of the number of files changed. It does not reflect 
individual alterations to a given file. This message does not 
appear if you have issued the CP SET IMSG OFF command line. 



Section 8: Format and Usage Rules for CP Commands 257 



CLOSE 



CLOSE 



EEilii®3§ Class: G 



Use the CLOSE command to terminate the spooling activity on any virtual 
spooled record or console device. If the file is an input reader file, 
the file being processed is purged unless SPOOL READER HOLD was 
previously specified (see the SPOOL command) . The effect of HOLD or 
NOHOLD for a particular file established by the SPOOL command can be 
overridden by specifying NOHOLD or HOLD, respectively, in the CLOSE 
command. If the file is an output file on a printer, punch, or console, 
the file is either gueued for output on a real unit record device, or, 
if the virtual output device is transferred (by use of the "SPOOL vaddr 
TO userid" command) , the file is gueued for input to the receiving user. 
You can specify a filename and filetype and an optional distribution 
code to aid in later identification of the file and its contents. The 
format of the CLOSE command is: 




| Reader r i 

| vaddr |HOld | 

I |NOHold| 

L L J 



ICOHsole 
IPrinter 
I PUnch 
| vaddr 



PUrge 

r n r 

IHOld | [DIst distcode] 
|NOHold| 

L L J L 



|NAme ffn [ft])| 
I 1 dsname (I 



j j j 



where: 



READER 
RDR 



closes all reader spool files. 



CONSOLE closes your virtual machined console spool file. Once a 
virtual console spool file is closed, it becomes a printer 
spool file and can be manipulated in the same way as any 
printer spool file (for example, it can be purged or 
changed) . 



PRINTER 
PRT 



closes all printer spool files. 



PUNCH 
PCH 



closes all punch spool files. 



vaddr is the virtual address (cuu) of the device to be closed. The 
address may represent a reader, console, printer, or punch. 

HOLD makes the spool file being closed unavailable for further 
processing, until it is specifically reguested or changed. 
This option, specified in the CLOSE command, overrides any 
previously specified HOLD or NOHOLD option for the files being 
closed. 

NOHOLD makes the spool file being closed available for further 
processing. Specify NOHOLD if a HOLD established by the SPOOL 
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CLOSE 

command is still in effect and the current active file is not 
to be held. 

You can release one of your own output files in HOLD status by 
using the CHANGE command. If an output file is spooled for 
another user (SPOOL FOR userid) , only the receiving virtual 
machine user can change the file status. The originator of 
the file may reclaim the file by using the TRANSFER command 
with the FROM option. If an output file is spooled to a user 
as an input file (SPOOL TO userid) , the HOLD option places the 
input file in HOLD status. The file then cannot be read by 
the virtual machine until it is changed to NOHOLD by the 
receiving virtual machine user. 

If an input file is closed with the HOLD option, the file is 
saved and not purged from the system. The saved file is 
available for virtual machine and user processing and is not 
placed in a user hold status. Input spool files that are 
closed are normally purged from the virtual machine. 

PURGE closes and immediately purges from the virtual machine the 
output spool files. No output file is produced. 

DIST distcode 

uses the one- to eight-character alphameric identification 
(distcode) on the output separators of printer and punch 
instead of the identification specified in the VH/370 
directory. The distribution code is changed for this file 
only and does not affect other files or change the VH/370 
directory. If the file is transferred to another user, this 
option has no effect. 

HAHE fn [ft] 

assigns identification to the spool file in the CHS format 
filename and filetype. The field, fn, is a one- to 
eight-character alphameric filename assigned to the file for 
identification. The field, ft, is a one- to eight-character 
alphameric filetype assigned to the file for identification. 
If ft is not specified, the filetype is set to blanks. 

HAKE dsname 

assigns identification to the spool file in a non-CHS format. 
The dsname field is a 1- to 24-character field suitable for 
specifying OS or DOS files (for example, SYS1.SYSLIB.HYHAC) . 
Only 20 characters of the 24-character dsname are displayed by 
QUERY, even though a name of up to 24 characters is valid. 

The table that follows shows the result of the CLOSE command, depending 
on how you had previously specified the SPOOL command options HOLD, 
NOHOLD, CONT, and NOCONT. The CLOSE command can result in a file being 
held, saved, or purged. 
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CLOSE 



Virtual 

Device 

Status 



(CLOSE 
Command 
Setting) 



SPOOL Command Options Set for a Virtual Device 



NOHOLD 
NOCONT 



| HOLD 
I NOCONT 



| NOHOLD 
| CONT 

I 



| HOLD 
| CONT 
I 



Normal EOF 
(default 
CLOSE) 



File released | File saved 
for proces— | 
sing | 



| File released |File held 
| for proces— | 
|sing | 



CLOSE 



File released |File saved 
for proces- | 
sing | 



| File released | File held 
I for proces- | 
|sing | 



CLOSE HOLD 



File saved |File saved {File held 



| File held 



CLOSE NOHOLD 



File released jFile released | File released |File released 
for proces— | f or proces— | f or proces— |for proces- 
sing |sing |sing |sing 



Note, "saved" 
HOLD status. 



means that the file is not purged and does not have 
A subseguent READ could read this file. 



Res£onses 



PRT ) 

PUN > FILE spoolid 

CON ) 



/TO ) 
id \ FOR J 



userid COPY nn 



f HOLD \ 
(NOHOLD J 



This response is received if multiple copies of the file are being 
processed, if the file is being transferred to another user, or if 
the file is placed in a USER HOLD status. 
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COUPLE 

COUPLE 

Privilege Class: G 

Use the COOPLE command to connect your virtual (non-dedicated) 
channel-to-channel adapter to another user*s virtual channel-to-channel 
adapter (or to another one of your own virtual channel-to-channel 
adapters) . The format of the COUPLE command is: 



| COUPLE | vaddrl [To] userid vaddr2 

i 



where: 

vaddrl is the virtual address (cuu) of your channel— to- channel 
adapter. 

[TO] userid 

is the user identification of the virtual machine to which 
vaddrl is to be connected. If vaddrl is to be connected to 
your own virtual machine, userid may be specified as an 
asterisk (*) . The user must be logged on and have a virtual 
channel-to-channel adapter defined. If the keyword TO is 
omitted, the userid cannot be "T" or "TO". 

vaddr2 is the virtual address (cuu) of the channel-to-channel adapter 
to be connected to vaddrl. 



CTCA vaddrl COUPLE TO userid vaddr2 

This is the response when you issue the COUPLE command. 

vaddrl is the address of your channel-to-channel adapter. 

userid is the identification of the receiving virtual machine. 

vaddr2 is the address of the channel-to-channel adapter of tb*j 
receiving user (or a different channel-to-channel adapter 
in your own virtual machine) . 

CTCA vaddr2 COUPLE BY userid vaddrl 

This is the response sent to the user specified by userid in the 
COUPLE command. 

vaddrl is the address of the issuing user's channel-to-channel 
adapter. 

userid is the identification of the user who issued the COUPLE 
command. 

vaddr2 is the address of the channel-to-channel adapter of the 
receiving user. 
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COUPLE 

CTCA vaddr 1 DROP PROM userid vaddr 

This response to the issuing user indicates that the virtual CTCA 
vaddr 1 was already coupled when the COUPLE conand was issued. The 
previous connection is completed. This response is always followed 
by the response: 

CTCA vaddrl COUPLE TO userid vaddr2 
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CP 



CP 

Privilege Class; Any 

Use the CP command if you are a CHS user and do not want to keep aware 
of which command environment you are in. 

The CP command is treated as a "null" by the control program and 
therefore can precede any other command if one or more blanks separate 
CP from the other command. The CP command is useful because it lets the 
CHS user enter commands without knowing which environment (CP or virtual 
machine) he is in. The format of the CP command is: 



i — i 

| CP | [command] I 

i i 



where: 

command is any CP command or string of CP commands that are separated 
by the logical line end symbol (#) and are valid for your 
privilege class. 



CP QUERY FILES 

— or — 
QUERY PILES 
can be entered from the CP or CHS command environment, 

Responses 
Hone 
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DEFINE 



DEFINE 



Privilege Class: G 



| Dse the DEFINE command to alter your virtual machine configuration or 
| channel operating mode. You can expand your configuration without 

making permanent changes, because the definitions are in effect for the 
| current terminal session only. If you redefine storage or define the 
| channel operating mode, the virtual machine is reset and IPL must be 

performed again. The format of the DEFINE command is: 




Header 

Printer 

PUnch [is] vaddr 

CONsole 

CTCa 

TIMer 

1403 

3211 

CHANnels [is 



] / SEL \ 
\ BMX J 



Line 



GBAF 



[As] vaddr |IBM[1,] I 
|TELE[2] 

L J 

cuu [3270] 
L3158 J 



vaddrl [As] vaddr 2 

T2314 

T2319 

T3330 [As] vaddr [CIL] nnn 

T3340 

T2305 

STORage [As] JnnnnnK) 
(nnM J 



where: 



READEB [AS] vaddr 
RDR 



PRINTER [AS] vaddr 
PRT 



PUNCH [AS] vaddr 
PCH 



CONSOLE [AS] vaddr 



adds a spooling card reader with the address 
specified by vaddr to the virtual machine 
configuration. 

adds a spooling printer with the address 
specified by vaddr to the virtual machine 
configuration. 

adds a spooling card punch with the address 
specified by vaddr to the virtual machine 
configuration. 

adds a virtual system console to the virtual 
machine at the address specified by vaddr. 
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DEFINE 



CTCA [IS] vaddr 



TIMER [AS] vaddr 
1403 [AS] vaddr 
3211 [AS] vaddr 



CHANNELS [AS] / SEL \ 
IBBXJ 



adds a virtual channel-to-channel adapter with 
the address specified by vaddr to the virtual 
■achine configuration. The control unit 
address must end in zero, and must not already 
be in use. Once the control unit is defined, 
other virtual devices nay not be defined for 
the sane CTCA. 

adds a pseudo timing device with the address 
specified by vaddr to the virtual machine 
configuration. 

adds a spooling 1403 printer with the address 
specified by vaddr to the virtual machine 
configuration. 

adds a spooling 3211 printer with the address 
specified by vaddr to the virtual machine 
configuration. The virtual 3211 printer 
supports LOADVFCB and the Index feature. 

redefines the channel mode of operation 
for the virtual machine to either selector or 
block multiplexer. Use of the SEL (selector 
channel) or BMX (block multiplexer channel) 
operand sets the mode of operation for ,all 
channels except virtual channel 0. Channel 
always operates in byte-multiplexer mode. The 
real or virtual channel-to-channel adapter 
always operates in selector mode. 

Block multiplexer mode may enhance the virtual 
machine's operating system by allowing the 
overlap of SIO operations. This is done by 
reflecting a channel condition code of back 
to the virtual machine rather than a channel 
busy signal. 

Note; The virtual machine is immediately reset 
when this set of operands is executed. 



r i 

LINE [AS] vaddr |IBH1 | 
|TELE2| 



GBAP cuu f3270"| 
L3158J 



vaddr 1 [AS] vaddr2 



adds a virtual 2701/2702/2703 communication 
line with the address specified by vaddr to the 
virtual machine configuration. 

IBH1 indicates that an IBM-type terminal (2741, 
1050, or equivalent) is on the 2701/2702/2703 
line. TELE2 indicates that a teletypewriter is 
on the 2701/2702/2703 line. 

defines a temporary virtual 3270 or 3158 (the 

system console used on the System/370 Model 

158) for the virtual machine. The cuu is the 
hexadecimal address for the device. 

redefines the device represented by vaddrl as 
vaddr2. The virtual address, vaddrl, must 
represent a defined device in the virtual 
machine configuration. 
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DEFINE 



T2314 [AS] vaddr [CYL] nnn 



T2319 
T3330 
T3340 
T2305 



STORAGE [AS] 



( nnnnnK 1 
\nnM J 



adds a temporary virtual disk of the specified 
type to the virtual machine configuration. 
The vaddr specifies the address of the disk, 
and lust not be on a virtual control unit 
already defined as a CTCA. CYL nn specifies 
the number of cylinders that the disk 
contains. 

redefines the size of the virtual storage for 
the virtual Machine as nnnnnK (where K 
represents 1024 bytes) or nnH (where H 
represents 1,048,576 bytes). The value 
specified becomes the new virtual storage size. 
Sizes nust be in 4K increments and are limited 
by the maximum value in the VH/370 directory 
entry. The minimum size you can specify is 8K. 
All entries not specified in a 4K increment are 
rounded up to the next 4K boundary. Changing 
the virtual storage size (increasing or 
decreasing) causes a virtual system reset and 
clears all virtual storage to binary zeros. 



Responses 

Responses are generated to confirm that the desired configuration change 
| has taken place. These responses do not appear on your terminal if you 
| have issued the CP SET IMSG OFF command line. 

type vaddr DEFINED 

where the possible values for type have the following meanings: 



lIE® 


Meaning 


DASD 


Direct access storage device 


TAPE 


Magnetic tape 


LINE 


Communication line 


RDR 


Card reader 


PRT 


Line printer 


PUN 


Card punch 


GRAF 


Graphics device 


CONS 


Console 


CTCA 


Channel-to-channel adapter 


CHANNELS = 


/ SEL\ 



is the channel mode of operation for the virtual machine. This 
response applies to all channels except channel (always a 
byte-multiplexer channel) and any channel that has a virtual or 
real channel-to-channel adapter (always a selector channel) . 



STORAGE - nnnnnK 

The minimum storage you may specify is 8K. 
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DETACH 

DETACH 

Privilege Class: G 

Use the DETACH command to remove a virtual device from the virtual 
machine. You can detach a previously attached device even if the device 
is currently in use. You can also detach devices that were attached 
because of VM/370 directory entries or during CP system initialization. 
You cannot detach volumes in the system SYSOWN list or devices 
containing minidisks that are in use. When you detach a virtual device, 
it becomes inaccessible to your virtual machine. If the device was 
previously attached to your virtual machine by an ATTACH command, it is 
released and becomes available for attachment to your virtual machine, 
another user, or the CP system. Tape devices are automatically rewound 
and unloaded when detached. If you detach a device that was previously 
attached to your virtual machine by the operator, a message is sent to 
the operator informing him that the device is free. The format of the 
DETACH command is: 



i 

| DETach | vaddr 

i 



where: 

vaddr is the virtual address (cuu) of the device to be detached from 
your virtual machine. 



Messages are sent to the user, the operator who issued the command, and 
the primary system operator (if different from the operator who issued 
the command) , notifying them that the DETACH was successful. 

type vaddr DETACHED 

This is the response you receive them you detach one of your own 
devices. You do not receive this response if you have issued the 
CP SET IMSG OFF command. 

type vaddr DETACHED BY operator 

This is the response you receive if an operator detaches one of 
your devices. 



r i 

type raddr DETACHED |userid| 

| SYSTEM | 
i j 

This is the response sent to the operator if you detach a 
previously attached device or if the operator detaches it from a 
user or the system. 
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DETACH 



r t 

type raddr DETACHED | user id | BY operator 

| SYSTEM | 

L J 

This is the response sent to the primary systea operator if he did 
not issue the DETACH comaand and the device had been previously 
attached. 

In the above responses, type is one of the following: 

Type Meaning 

DASD Direct access storage device 

TAPE Magnetic tape 

LINE Communication line 

RDR Card reader 

PRT Line printer 

PUN Card punch 

GRAF Graphics device 

CONS Console 

CTCA Channel-to-channel adapter 

Di2V Any other device 

CTCA vaddr DROP FROM userid vaddr 

This is the response if the device detached was a virtual CTCA 
connected (via the COUPLE command) to another CTCA on the virtual 
machine specified by the userid. This response is always followed 
by the response: 

CTCA vaddr DETACHED 

unless the SET IMSG OFF command was issued. 



268 IBM VM/370: Command Language Guide for General Users 



DIAL 



DIAL 



Privilege Class; Any 



Use the DIAL command to logically connect a switched line, leased line, 
or locally attached teriinal to a previously logged on multiple-access 
virtual Machine. Once the connection is made, your terminal operates 
entirely under the control of that virtual machine. The DIAL command 
matches your terminal to the equivalent type defined in the 
multiple- access virtual machine. If no matching terminal type exists. 



the connection cannot be made 
format of the DIAL command is: 



and an error message is issued. 



The 



DIAL 



userid [vaddr] 



where: 
userid 

vaddr 



is the identification of a virtual machine that is 
currently logged on. 

is the address of the virtual communication line to which 
the connection is made. 



Botes: 
1.~A 



DIAL command is accepted only at logon time, and only as a 
substitute for a LOGOH command. The type of terminal used must be 
supported by both VM/370 and the multiple-access virtual machine. 
The only exception is the 3277 Display Station Model 1 
(480-character screen) . This display terminal, if used, must be 
supported by the multiple-access virtual machine. VM/370 support 
of this model is limited to the DIAL facility only. See the 
VM/370: Terminal Oser's Guide for details on running and gaining 
access to multiple-access machines. 



2. If the DIAL command is issued from a real 3277 terminal, the 
virtual system must use the CP command BESET to drop the dialed 
connection. DIAL is not supported for the 3066 system console. 



3. The CP DIAL command is not supported for terminals 
iCP lines in a 3704/3705 control unit. 



that are using 



Responses 

DIALED TO userid vaddr 

is the message sent to the user indicating that a logical 
connection has been made. 

(GRAF raddr ) 

^LIHE raddr > DIALED TO userid DIALED - nnn 



DEV rid ) 



is the response to the primary system operator. It indicates a 
successful connection to the virtual machine (userid) and the 
total number of VH/370 lines (nnn) currently connected to other 
virtual machines. DEV rid indicates the resource identification 
of a 3704/3705 line. 

Bote: The terminal remains connected to and under the control of 
the virtual machine until that virtual machine terminates the 
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DIAL 



communication. At that time the user receives the following 
■essage: 

DROP FROM userid vaddr 

this message is sent to the user when the line is disabled. 



GRAF raddr ) 

LIHE raddr \ DROP FROM userid DIALED = nnn 

DEV rid ) 

is the Message sent to the primary systea operator. 
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DISCOHH 

DISCONN 

P rivil ege Class; Any 

Use the DISC0N1 command to disconnect the terminal froi the VH/370 
systei: the virtual machine continues operation. When DISCONN is issued 
from the virtual Machine, a disconnect-time Message is printed at the 
virtual machine's teriinal and at the primary system operator's console. 
The terminal remains disconnected until it is reconnected via a LOGON 

> command. The virtual machine is logged off 15 minutes after an attempt 
is made to read from the terminal or if the virtual machine goes into a 

| disabled WAIT state. 

If your terminal connection is broken because of terminal, line, or 
TP control unit errors, CP places the virtual machine in disconnect mode 
for up to 15 minutes and your virtual machine does not continue to run. 
If you log on within 15 minutes, your virtual machine can continue 
operating. If you do not log on within the 15-minute interval, the 
virtual machine is logged off. 

Unless the CP command, SPOOL CONSOLE START, is issued to spool the 
virtual console output, all "writes" or output messages to the virtual 
console are ignored. When the terminal is reconnected via the normal 
LOGON procedure, the terminal is placed in CP console function mode. To 
resume execution of the virtual machine, enter the BEGIN command. The 
format of the DISCONN command is: 



i - ■ •■' -' ■■ ■ - "- ■ - <• — - ■ ■ • ■- - i 

| DISConn | [HOld] I 

i i 

where ; 

HOLD specifies that the communication line is not to be disabled. 
This option allows you to disconnect your terminal, and, at 
the same time, to avoid the process of telephone dialing into 
the system to access your virtual machine again. If specified, 
control returns to CP and the "YM/370 online" message, is 
displayed. 

Responses 

Nhen the DISCONN command is issued, the disconnect time message is 
issued. 

DISCONNECT AT hh:mm;ss zone weekday mm/dd/yy 

is the response to the user who issued the command. 

(GRAF raddr) 

< LINE raddr > DISCONNECT userid USERS = nnn 

( DEV rid j 

is the response to the primary system operator informing him 

that the user represented by "userid" has been disconnected from 

the VH/370 system. The "nnn" is the total number of users 

| remaining in the system. The response "rid" indicates the 

| resource identification. 
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DISPLAY 



Privilege Class: G 



Ose the DISPLAY 
components: 



command to examine the following virtual machine 



• Virtual storage locations 

• General registers 

• Floating-point registers 

• Control registers 

• Program status word (PSW) 

• Channel address word (CAW) 

• Channel status word (CSW) 

If a command line with an invalid operand is entered, the DISPLAY 
command terminates when it encounters the invalid operand; however, any 
previous valid operands are processed before termination occurs. 
Storage locations, registers, and control words can be displayed using a 
single command line. The format of the DISPLAY command is: 



j Display c \ 


/ r 

/ | hexloc 
J IKhexloc 
1 | Lhexloc 
1 | Thexloc 

1 1 ^ 

1 L 


t r r t 
1| |(-)|hexloc2 | 

II ll:/lJND | 
1| I L J 

III r t 
| |{ . }|bytecount | 
J 1 IJND | 

L L J 


J 




/ r 

( Gregl | 

\ Yregl | 

J Xregl | 


r t -% 
/-\|reg2| | 
\ : J IEHD | | 






1 L 


r t 1 

{ • }|regcount | | 

I1ND | | 

L J J 






1 Psw 
\ CAW 
\ CSW 







where: 



hexlod 

Lhexlod 

Thexloc 1 

Khexlod 





is the first, or only, hexadecimal storage location 
whose contents are to be displayed at the terminal. If 
L is specified, the storage contents are displayed in 
hexadecimal. If T is specified, the storage contents 
are displayed in hexadecimal, with EBCDIC translation. 
If K is specified, the storage keys are displayed in 
hexadecimal. 



If hexlod is followed by a period and is not on a 
fullword boundary, it is rounded down to the next 
lowest fullword. 



If hexlod is not specified, the 
storage location 0. If L, T, or K 



display begins at 
are entered either 
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-)hexloc2 
•/OP. 



without any operands, or followed immediately by a 
blank, the contents of all storage locations are 
displayed. If L, T, or K are not specified and this is 
the first operand, then the default value of zero is 
assumed. The address, hexlod, may be one to six 
hexadecimal digits; reading zeros are optional. 

is the last of the range of hexadecimal storage 
locations whose contents are to be displayed at the 
terminal. Either — or : must be specified to display 
the contents of more than one location by storage 
address. If hexloc2 is not specified, the contents of 
all storage locations from hexlod to the end of 
virtual storage are displayed. If specified, hexloc2 
must be equal to or greater than hexlod and within the 
virtual storage size. The address. hexloc2, may be 
from one to six hexadecimal digits; leading zeros are 
optional. 



{ . }bytecount 
END 



is a hexadecimal integer designating the number of 
bytes of storage (starting with the byte at hexlod) to 
be displayed at the terminal. The period, ., must be 
specified to display the contents of more than one 
storage location by byte count. The sum of hexlod and 
bytecount must be an address that does not exceed the 
virtual machine size. If this address is not on a 
fullword boundary, it is rounded up to the next highest 
fullword. The value, bytecount, must have a value of 
at least one and may be from one to six hexadecimal 
digits; leading zeros are optional. 



Gregl 



is a decimal number from 0—15 or a hexadecimal integer 
from 0-F representing the first, or only, general 
register whose contents are to be displayed at the 
terminal. If G is specified without a register number, 
the contents of all the general registers are displayed 
at the terminal. 



Yregl 



is an integer (0, 2, 4, or 6) representing the first, 
or only, floating— point register whose contents are to 
be displayed at the terminal. If Y is specified 
without a register number, the contents of all of the 
floating— point registers are displayed at the 
terminal. 



Xregl 



is a decimal number from 0-15 or a hexadecimal number 
from 0— F representing the first, or only, control 
register whose contents are to be displayed at the 
terminal. If X is specified without a register number, 
the contents of all of the control registers are 
displayed at the terminal. If Xregl is specified for a 
virtual machine without extended mode operations 
available, only control register is displayed. 



{7}£ 



-)reg2 
IEHD 



is a number representing the last register whose 
contents are to be displayed at the terminal. Either — 
or : must be specified to display the contents of more 
than one register by register number. If reg2 is not 
specified, the contents of all registers from regl 
through the last register of this type are displayed. 
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The operand, reg2, must be equal to or greater than 
regl. If Gregl or Xregl are specified, reg2 may be a 
decimal number from 0-15 or a hexadecimal number from 
0— F. If Yregl is specified, reg2 may be 0, 2, 4, or 
6. The contents of registers regl through reg2 are 
displayed at the terminal. 

{ . }regcount is a decimal number from 1 to 16 or a hexadecimal 
END number from 1 to F specifying the number of registers 

(starting with regl) whose contents are to be displayed 
at the terminal. If the display type G or X is 
specified, regcount can be a decimal number from 1 to 
16 or a hexadecimal number from 1 to F. If display type 
Y is specified, regcount must be 1, 2, 3, or 4. The 
sum of regl and regcount must be a number that does not 
exceed the maximum register number for the type of 
registers being displayed. 

PSW displays the current virtual machine PSW (program 

status word) as two hexadecimal words. 

CAR displays as one hexadecimal word the contents of 

hexadecimal location 48 (channel address word) . 

CSW displays as two hexadecimal words the contents of the 

channel status word (doubleword at hexadecimal location 
40). 



When multiple operands are entered on a line for location or register 
displays, the default display type is the same as the previous explicit 
display type. The explicit specification of a display type defines the 
default for subsequent operands for the current display function. 
Blanks are used to separate operands or sets of operands if more than 
one operand is entered on the same command line. Blanks must not be 
used to the right or left of range or length delimiters (: - .), 
unless it is intended to take the default value of the missing operand 
defined by the blank. For example: 

display 10 20 T40 80 G12 5 L60-100 

displays the following: 

hexadecimal location 10 

hexadecimal location 20 

hexadecimal location 40 with EBCDIC translation 

hexadecimal location 80 with EBCDIC translation 

general register 12 

general register 5 

hexadecimal locations 60 through 100 



Res£onses 

One or more of the following responses is displayed, depending upon the 
operands specified. 
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xxxxxx wordl word2 word3 word4 [key] *EBCDIC TRANSLATION* 

This is the response you receive when you display 
locations; xxxxxx is the hexadecimal storage location o 
Wordl is displayed (word-aligned) for a single 
specification. Up to four words are displayed on a line, 
optionally, by an EBCDIC translation of those four words, 
are printed for unprintable characters. Multiple line are 






.W\*UW.1W11*9 . 



11 uiauoianuu iu 



requested (Thexloc) , alignment is made to the next lowe 
boundary; otherwise, alignment is made to the next lower 
boundary. If the location is at a 2K page boundary, the 
that page is also displayed. 



storage 

f wordl. 

location 

followed. 

Periods 

used (if 

tionnT/i — 

EiD\.U±\~ lb 

r 16-byte 

fullword 

key for 



K§X§ : 



xxxxxx TO xxxxxx 



KEY = kk 



This is the response you receive when you display storage keys; 
xxxxxx is a storage location and kk is the associated storage key. 



General Registers 



GPR n = genregl genreg2 genreg3 genregt* 

This is the response you receive when you display general 
registers; n is the register whose contents are genregl. The 
contents of the following consecutive registers are genreg2 and so 
on. The contents of the registers are displayed in hecadecimal. 
Up to four registers per line are displayed for a range of 
registers. Multiple lines are displayed if required, with a 
maximum of four lines needed to display all 16 general registers. 



Floating-Point Registers 



FPR n = xxxxxxxxxxxxxxxx . xxxxxxxxxxxxxxxxx E xx 

This is the response you receive when you display floating-point 
registers; n is the even-number floating-point register whose 
contents are displayed on this line. The contents of the requested 
floating-point registers are displayed in both the internal 
hexadecimal format and the E format. One register is displayed per 
line. Multiple lines are displayed for a range of registers. 
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Control Registers 

ECR n = ctlregl ctlreg2 ctlreg3 ctlreg4 

This is the response you receive when yon display control 
registers; n is the register whose contents are ctlregl. The 
contents of the following consecutive registers are ctlreg2 and so 
on. The contents of the reguested control registers are displayed 
in hexadecimal. Op to four registers per line are displayed. 
Multiple lines are displayed if reguired. 



£SW 

PSW = xxxxixxi xxxxxxxx 

The contents of the PSW are displayed in hexadecimal. 



CAW 



CAW = XXXXXXXX 

The contents of the CAW (hexadecimal location 48) are displayed in 
hexadecimal. 



CSW 



CSW = xxxxxxxx xxxxxxxx 

The contents of the CSW (hexadecimal location 40) are displayed in 
hexadecimal. 

Press the Attention key (or its eguivalent) to terminate this 
function while data is being displayed at the terminal. When the 
display terminates, another command may be entered. 
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DUMP 



Privilege Class; G 

Use the DUMP command to print the contents of various components of the 
virtual machine on the virtual spooled printer. The following items are 
printed: 

• Virtual program status word (PSW) 

• General registers 

• Floating-point registers 

• Control registers (if you have the ECMODE option specified in your 
VM/370 directory entry) 

• Storage keys 

• Virtual storage locations 

The DUMP command prints the virtual PSK and the virtual registers 
(general, floating-point, and control) . If only this information is 
desired, at least one virtual address must be specified, such as: 

DUMP 

The output format for the virtual storage locations is eight words 
per line with EBCDIC translation on the right. Each fullword consists 
of eight hexadecimal characters. All the rest of the information (PSfi, 
general floating-point and storage keys) is printed in hexadecimal. If 
you have the ECMODE option in your VM/370 directory entry, the control 
registers are also printed. To print the dump on the real printer, a 
CLOSE command must be issued for the spooled virtual printer. The 
format of the DUMP command is: 



DUMP 



/r 



t r 



I Lhexloc 1 1 \j - \\ hexloc2 
I s /HMD 



|Thexloc1| | 
| hexlodH 
I || r -, 
L J |{ .}|bytecount| 
I IMD I 



[*dumpid] 



where: 

Lhexlod 
Thexlod 
hexlod 




is the first or only hexadecimal storage location to 
be dumped. If you enter L or T without operands, the 
contents of all virtual storage locations are dumped. 

The address, hexlod, may be one to six hexadecimal 
digits; leading zeros are optional. If hexlod is not 
specified, the dump begins at storage location 0. 

If hexlod is followed by a period and is not on a 
fullword boundary, it is rounded down to the next lowest 
fullword. 
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J-)hexloc2 is the last hexadecimal storage location whose contents 
I : ) END are to be dumped to the printer. The operand, hexloc2, 
must be equal to or greater than hexlod and within the 
virtual storage size. To dump to the end of storage, you 
can specify BUD instead of hexloc2 or you can leave the 
field blank, since the default is END. If you specify 
:END or -END, the contents of storage from hexlod to END 
are dumped. The contents of storage locations hexlod 
through hexloc2 are printed with EBCDIC translation at 
the printer. The operand, hexloc2, may be from one to six 
hexadecimal digits; leading zeros are optional. 

{ . jbytecount is a hexadecimal integer designating the number of bytes 

END of storage (starting with the byte at hexlod) to be 

dumped to the printer. The period, ., must be specified 

to dump the contents of more than one storage location by 

byte count. The sum of hexlod and bytecount must be an 

| address that does not exceed the virtual machine size. 

| If this address is not on a fullword boundary, it is 

| rounded up to the next highest fullword. The value, 

bytecount, must be one or greater and can be no longer 

than six hexadecimal digits. Leading zeros are 

optional. 

♦dumpid can be entered for descriptive purposes. If specified, 
it becomes the first line printed preceding the dump 
data. Up to 100 characters, with or without blanks, may 
be specified after the asterisk prefix. No error 
messages are issued, but only 100 characters are used, 
including asterisks and embedded blanks. 

Osage: 

Normally, you should define beginning and ending dump locations in the 
following manner: 

dump Lhexlod— hexloc2 

dump Lhexlod. bytecount 

dump Lhexlod— hexloc2 hexlod. bytecount * dumpid 

If, however, a blank follows the type character (L or T) or the 
character and the hexloc, the default dump starting and ending locations 
are assumed to be the beginning and/or end of virtual storage. Blanks 
are used to separate operands or sets of operands if more than one 
operand is entered on the same command line. Blanks must not be used to 
the right or left of range or length delimiters ( : — . ) , unless it is 
intended to take the default value of the missing operand defined by the 
blank. Thus, all of the following produce full storage dumps: 



dump 1 




dump t: 




dump 


0-end 


dump t 




dump 1. 




dump 


l:end 


dump - 




dump t. 




dump 


t:end 


dump : 




dump 0— 




dump 


0:end 


dump . 




dump 0: 




dump 


Lend 


dump 1— 




dump 0. 




dump 


t.end 


dump t— 




dump l—i 


end 


dump 


O.end 


dump 1: 




dump t— i 


end 






g produc< 


es 


three f 


all 


dumps: 




dump 1 . 


t 










dump — . 


: 
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Responses 

DUMPING LOC hexloc 

As the dump is processing, the following message is displayed at 
the terminal indicating that the dump is continuing from the next 
64K boundary: where hexloc is the segment (64K) boundary address 
for the dump continuation, such as 020000, 030000, or 040000. 

If you press the Attention key, or its equivalent, on the terminal 
while the message is being displayed, the dump function is 
terminated. 

COMMAND COMPLETE 

This response indicates normal completion of the dump function. 
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ECHO 



Privilege CjLass: G 



Ose the ECHO command to place the terminal in the ECHO environment. 
When in the ECHO environment, any input line entered is transmitted 
unchanged back to the terminal a specified number of times. To 
terminate this transmission (for example, vhen you vant to enter a 
different data line) , press the Attention key (or its equivalent) . When 
the specified number of lines is displayed or the Attention key is 
pressed, another read to the terminal is issued to accept another data 
line. Bote that no line editing is done; thus, the output line is the 
same as the input line and may contain any of the logical line editing 
symbols. The format of the ECHO command is: 



1 — 








1 
1 


ECho 


1 
1 


r n 1 

mm i 


1 
1 




1 
1 


il i i 

i. j | 


L. . 









where: 
nn 



is the number of times the line is to be sent. The default is 
1. An invalid entry (that is, one that is greater than 99 or 
contains non-numeric characters) is treated as 1. 



Responses 



ECHO ENTERED; TO TERHINATE TEST, TYPE END 



This message is displayed after the ECHO command is invoked to 
indicate that the ECHO environment has been entered. 



ENTBR LINE 



This message reguests the input line to be entered, 
returns the terminal to the CP command environment. 



A reply of END 



280 IBM VH/370: Command Language Guide for General Users 



GC20- 1804-3 Page Modified by TNL GN20-2659 

EXTERNAL 

EXTERNAL 

£Eizil®3^ Class: G 

Use the EXTERNAL command to simulate an external interrupt to the 
virtual machine and return control to that machine. This simulates 
pressing the interrupt key on the real computer console, or other 
functions which cause an external interrupt. Control is given to the 
virtual machine immediately. The format of the EXTERNAL command is: 



I I r -. I 

I EXTernal | |code| I 

I I I i*0 | | 



where : 

code is the interrupt code, a hexadecimal number to be associated 
with the external interrupt. Valid codes are 1005 (CPU 
Timer) , 1004 (Clock Comparator) , and all codes less than or 
egual to X'FF'. The default is the External Interrupt Button 
on the system console, X'40'. 



Responses 

None. Since control is given to the virtual machine, any response is 
from virtual machine processing. 
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I INDICATE 

I ££±lil§3® Class: G 



| Use the INDICATE command to display at your terminal, the use of and 
| contention for major system resources. Use INDICATE LOAD to display 
| system load conditions. Use INDICATE USER to display the total amount of 
| certain resources used by your virtual machine during the current 
| terminal session. Use the INDICATE USER command before and after the 
| execution of a program to indicate the execution characteristics of that 
| program in terms of the resources used. 

| The format of the INDICATE command is: 



I r- 

I I 

I I 

I I 

I I 

I L 



INDicate 



I r t 

I 1 1 A D | 

I I USER * | 

I L J 



| LOAD 
I 

| USER * 



displays CPU use, CPU contention, main storage use, and main 
storage contention. 

displays the amounts of system resources used by your virtual 
machine in the current terminal session. 



I Response for INDICATE LOAD 



| CPU-nnn% Ql-nn Q2-nn STORAGE-nnnX RATIO-n.n 



| where : 



CPU-nnnX - is the percentage of total CPU usage. The CPU figure is a 
smoothed value of the percentage of time that the system is running. 
The value is smoothed because instantaneous values can be 
misleading. 

Q1-nn Q2-nn - represent the contention for the CPU in terms of the 
smoothed number of users in gueue 1 and gueue 2 (maintained by the 
scheduler) . 

STORAGE-nnn% - is the percentage of main storage usage. This is a 
smoothed ratio of the sum of the estimated working sets of users in 
gueue 1 and gueue 2 to the number of pageable pages in the system. 

RATIO-n.n - represents the contention for main storage. This 
scheduler contention ratio is a smoothed value and is defined as: 

E+M 

RATIO = 

M 



282 IBM VM/370: Command Language Guide for General Users 



GC20-1804-3 Page Modified by TNL GN20-2659 

INDICATE 



where: 

E the number of users waiting to be allocated main storage by the 
scheduler and, therefore, temporarily resident in the scheduler's 
eligible lists. 

M the number of users in gueue 1 and gueue 2. 

Thus, RATIO is the ratio of users now active to users being serviced 
and is 1.0 for optimum response. Optimum response occurs when enough 
storage exists to accommodate all active users, assuming that the 
system at this time is not CPU bound. 

If E and M are both zero, the value of RATIO is set to 1.0. 

When BATI0=1.5 and M=8, then 4 users are in the eligible lists 
waiting to be allocated main storage space by the scheduler. While 
in the eligible list, the users are subject to scheduler 
discrimination, as defined by the biased scheduler. 



Response for INDICATE USER 

PAGES: RES-nnnn WS-nnnn READS=nnnnnn WRITES=nnnnnn DISK-nnnn DRUM-nnnn 
VTIME=nnn:nn TTIME=nnn:nn SIO=nnnnnn RDR-nnnnnn PRT-nnnnnn PCH-nnnnnn 

where : 

• RES-nnnn - is the current number of your virtual storage pages 
resident in main storage. This number is taken at an instant of time 
during the execution of the INDICATE command. 

• WS-nnnn - is the most recent system estimate cf your working set 
size. 

• READS=nnnnnn - is the total number of page reads that have occurred 
for you since you logged on or since the last ACNT command was issued 
for your virtual machine. 

• WRITES=nnnnnn - is the total number of pages written for you since 
you have logged on or since the last ACNT conmand was issued for your 
virtual machine. 

• DISK-nnnn - is the current number of virtual pages allocated for you 
on the system paging disk. This number is taken at an instant of 
time during the execution of the INDICATE command. 

• DRUM-nnnn - is the current number of virtual pages allocated for you 
on the system paging drum. This number is taken at an instant of time 
during the execution of the INDICATE command. 

• VTIME=nnn:nn - is your total virtual machine time since you logged on 
or since the last ACNT command was issued for your virtual machine. 

• TTIME=nnn:nn - is your total virtual machine time and total CPU time 
(virtual and overhead) that you have used since you logged on or 
since the last ACNT conmand was issued for your virtual machine. 

• SIO=nnnnnn - is the total number of non-spooled I/O reguests that you 
have issued since you logged on or since the last ACNT command was 
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issued for your virtual machine. 

• RDR-nnnnnn - is the total number of virtual cards read since you 
logged on or since the last ACNT command was issued for your virtual 
machine. 

• PRT-nnnnnn - is the total number of virtual lines printed since you 
logged on or since the last ACNT command was issued for your virtual 
machine. 

• PCH-nnnnnn - is the total number of virtual cards punched since you 
logged on or since the last ACNT command was issued for your virtual 
machine. 
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IPL 

Privilege Class: G 

Use the IPL command to simulate an initial program load function for a 
virtual machine. IPL simulates the LOAD button and the device address 
switches on the real computer console. The specified virtual address is 
accessed and the reguired input/output operations are performed to 
retrieve the IPL data. Optionally, the IPL procedure can be stopped 
| just before loading the virtual PSW except when initial program loading 
| a named system. Also, parameters can be passed to the virtual machine's 
general registers. When the simulated load function is complete, CP 
initiates execution of the virtual machine by loading the IPL PSW which 
was stored during the simulation process. The format of the IPL command 
is: 

I Ipl I | r n 

I I \ ICLear | 

vaddr [cylno] |NOCLear| [STOP] [ [PARM {p1 p2... } ] 

L J 

| | y systemname 

i : i 

where : 

r t 

vaddr [cylno] |CLEAR | [STOP] [PARM {p1 p2...}] 
|N0CLEAR| 

L J 

simulates the IPL function when loading by device address. 

The address, vaddr, is the virtual address (cuu) of the device 
that contains the nucleus to be loaded. 

The number, cylno, is the cylinder containing the IPL data. 
If this operand is specified, CP loads the IPL data from the 
specified virtual cylinder instead of from the default, 
virtual cylinder zero. This operand is valid only for virtual 
direct storage devices. 

The CLEAR operand clears the virtual storage space to binary 
zeros before the operating system is loaded; NOCLEAR does not 
| clear storage. Both of these operands are invalid if the user 

| specifies systemname in the IPL command line. 

The STOP operand stops the virtual machine during the IPL 
procedure just before the initial PSW is loaded. The STOP 
operand provides the virtual simulation of the IPL procedure 
for a real machine in instruction step mode. The STOP operand 
is invalid with the IPL systemname form of the command, when 
the virtual machine stops, you can issue CP commands. For 
example, if you are loading OS or OS/VS into your virtual 
machine, you can use CP commands to store data into low 
storage to load an alternate nucleus or to alter the size of 
virtual storage. To restart the virtual machine, issue the 
BEGIN command. 

The PARM p1 p2... operand passes up to 64 bytes of data 
(including embedded blanks) to your virtual machine's general 
registers (four bytes per register) , starting with the high 
order byte of general register 0, whenever PARM is specified. 
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the remaining characters in the command line are treated as 
parameters to be passed to the virtual machine; therefore, 
PARM must be the last operand entered on the command line. 

systemname [PARM {p1 p2...}] 

simulates the IPL function when loading a named system that 
was previously saved via the SAVESTS command. 

The systemname operand is the name of the previously saved 
system. It is loaded into virtual storage and given control. 
For more information about saved systems, see the V M/370 : 
Sis tern Programmers Guide. 

The PARM p1 p2... operand passes up to 6U bytes of data 
(including embedded blanks) to your virtual machine's general 
registers (4 bytes per register) , starting with the high order 
byte of general register 0. Whenever PARM is specified, the 
remaining characters in the command line are treated as 
parameters to be passed to your virtual machine; therefore, 
PARM must be the last operand entered on the command line. 

Note: Care must be used when passing parameters to a named 
system (systemname) , Named systems expect certain registers to 
be initialized when they are given control. Indiscriminate 
use of the PARM option could overlay a previously initialized 
register causing unpredictable results. 



Responses 

After a successful IPL, any responses you receive are those from the 
operating system that was loaded and initialized. 
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LINK 

Privilege Class: G 

Use the LINK command to make a device that is associated with another 
virtual machine available to your virtual machine configuration, based 
upon information in that user's VM/370 directory entry. The format of 
the LINK command is: 

i 1 

| LINK | [To] userid vaddrl [is] vaddr2 [mode] [[PASS=] password] | 

i 1 

where : 

[TO] userid is the name of the user whose VM/370 directory is to be 

searched for device vaddrl. An asterisk (*) is used to 

specify that the device is in your own VM/370 directory. 

If the keyword TO is omitted, the userid may not be TO or 

T. 

vaddrl is the virtual device address (cuu) in the VM/370 
directory for that userid. 

[AS] vaddr2 is the virtual address (cuu) which is to be assigned to 
the device for your virtual machine. If the keyword AS is 
omitted, vaddr may not be A. If your virtual machine has 
the ECMODE option, any address up to X'FFF* is valid; 
otherwise, any address up to X'5FF' is valid. 

mode is the access mode; the primary access requested 

(read-only, write, or multiple) , and the alternate access 
(read-only or write) desired if the primary access is not 
available. Valid modes are: 

Mode Meaning 

R Read— only access. The link is not done if any other 
user has the disk in write status. R is the default 
mode if the link is to another userid. 

RR Read-only access. The link is established even if 
another user has the disk in write status. 

W Write access. The link is not done if any other user 
has the disk in read or write status. 

WR write and read access. If another user has the disk 
in read or write status, an alternate access of 
read— only is acceptable. 

M Multiple access. This means that a write-link is to 
be given to the disk unless another user already has 
write access to it, in which case no link is to be 
done. 

MR Write-link. If another user already has write access 
to the disk, a read-link is to be done. 

MW Write-link. This link is established in all cases. 

| Caution; Multiple write access under CMS can produce 

I unpredictable results. 

If the mode is omitted, the default is R if the userid is 
another user; if you are linking to one of your own 
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disks, the default is the "user access node" of either B, 
W, or M as specified in the VM/370 directory for your 
disks. 

PASS= password is a one— to eight— character string that must match the 
access mode password for device vaddrl in the VM/370 
directory for the user (userid) specified. The password 
should be specified only when the LINK is executed by a 
virtual machine (for example, from CHS) , since the 
password is not print suppressed when included with the 
LINK command. The password cannot be the same as any of 
the access modes (B, BR, W, WB, H, MB, or MM) if the 
default mode is to be used. 

Note : The access mode password should not be confused 
with a user password. 

If you link to one of your own disks, no password is required. Also, 
if the link is to a device whose password is ALL, meaning that the 
device can be used by all users, the password is not required. However, 
if the link is to any other userid, a password for the desired device 
must be provided. 

Note: The access allowed by the LINK command to the vaddrl device 
belonging to userid is summarized below. You read the columns down to 
determine the type of link that results. The first row indicates the 
primary (and, optionally, the alternate) access mode requested. The 
second row indicates whether read, write, or multiple passwords exist in 
the VM/370 directory for the disk being linked. The third row indicates 
whether the disk is already being used, and if so, the mode of its 
access. The last row indicates the type of link established. For 
example, the third column is interpreted as follows: if you request a 
read access link (B) to a disk that has a read password defined and that 
already is accessed in read mode, you can establish a read link. 

i 1 

| Primary access requested: BBBBB NWHNHN MHHHHH 

| alternate access (if any) : B B B B W 



| Bead password in directory: N Y Y ¥ I 

(write password in directory: N Y Y Y Y Y 

|Hult. password in directory: N Y Y Y Y Y 



1 

|Any existing links: NBNN NBBNH 


N B H W H | 


1 — — - — 

lAccess established: NBBNB NWNBNB 

1 .,..„_.,.,,. 


N W N N B N | 


1 .......... u. -., . ,.. 

Iwhere: N=no or none; B=read; W=write; M=multiple; Y=yes 

L 


• 



Besponses 

ENTEB BEAD PASSfiOBD: 
IIIIHII 

Type the read password over the mask to obtain read access to the 
desired disk. 

ENTEB NBITE PASSWOBD: 
UlllIU 

Type the write password over the mask to obtain write access to the 
desired disk. 
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EHTEB HOLT PASSWORD: 
11111111 

Type the multiple password over the mask to obtain write access to 
a disk for which other users lay already have access. 

Bote; If LINK is issued from a virtual Machine with the password 
included on a command line, and the password is incorrect, then CP 
counts these incorrect passwords. If a total of ten such incorrect 
passwords is entered, the LIHK command from a virtual machine is 
subsequently disallowed for that user for the remainder of the 
session. LIHK can still be issued directly from the terminal (that 
is, in CP command mode) , or the LIHK command can be reinstated as a 
valid command from your virtual machine by logging off and logging 
on again. (This procedure is designed to protect password security 
if a virtual machine issues the LIHK command repeatedly with trial 
passwords.) 

DASD vaddr2 LIHKED B/0 

This response indicates that a read-only link to the given disk is 
established, for a LIHK request with a mode of B or BR, and that no 
other users are linked to the same disk in read/write mode. 

DASD vaddr2 LIHKED H/W 

This response indicates that a read/write link to the given disk is 
established, for a LIHK request with a mode of W, WB, H, MB, or MI, 
and that no other users are linked to the same disk. 



DASD vaddr2 LIHKED B/0; B/W BY /nnn USEBS)|; B/0 BY ( nnn USEBS\| 



userid /[ 1 userid f\ 



i j 

This response indicates that a read— only link to the given disk is 
established for a LIHK request with a mode of BB, but warns that 
the disk is in read/write use by some users and possibly in read 
use by some users. If only one user has access, the number of users 
(nnn USERS) is replaced by userid. 

DASD vaddr2 LIHKED B/W; B/0 BY (nnn USEBS) 

(userid J 

This response indicates that a read/write link to the given disk is 
established for a LIHK request with a mode of H, MB, or MW, and 
informs you that the disk is also in read-only use by userid or by 
nnn users. (Ho other users have a read/write link to the disk.) 

r i 

DASD vaddr2 LIHKED B/H; B/H BY ( nn USEBS\ |; B/0 BY (nnn USEBS) | 



( nn USEBSl |; B/0 BY (nnn USEBS) 
\ userid J | \ userid / 



This response indicates that a read/write link to the given disk is 
established for a LIHK request with a mode of HW, but warns you 
that the disk is also in read/write use by some users and possibly 
in read use by some users. If only one user has access, the number 
of users (nnn USEES) is replaced by userid. 
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LOADVFCB 

£Eili2®3§ Class: G 

Use the LOADVFCB command to specify the forms control for a virtual 
spooled 3211 printer* The format of the LOADVFCB command is: 

i 1 

| LCADVFCB | vaddr FCB name [Index [nn]] | 

i i 

w her e : 

vaddr is the virtual device address (cuu) of the virtual 3211 
spooled printer. 

FCB is a required reserved word meaning Forms Control Buffer. 

name is a system-defined name for the 3211 FCB image which is to be 
the controlling virtual FCB image. 

There is only one VM/370 FCB image provided; its name is FCB1 
and its format is as follows: 

Space 6 lines/inch 
Length of page 66 lines 



Line 


Ch 


annel Skip 


Represented 


Sp 


ecif ication 


1 


1 


3 




2 


5 




3 


7 




4 


9 




5 


11 




6 


13 




7 


15 




8 


19 




10 


21 




11 


23 




12 


64 




9 



INDEX [nn] 

is the number of the print position that is the first print 
position. The value, nn, must be a number from 1 through 31; a 
leading zero need not be specified. If the keyword INDEX is 
specified without a value, the index defaults to the value 
specified in the FCB macro. See the VM/370: System 
P£55£ammer^s Guide for a discussion of the FCB macro and forms 
control images. 

Note: The LOADVFCB command may be used with installations that do not 
have a 3211. The virtual machine's VM/370 directory entry must indicate 
a 3211, even though the program and operating system have a 1103 
defined. Then the LOADVFCB command can be used to obtain a virtual 
forms control image for 1403 printers so that programs that use printer 
overflow sensing may be spooled to disk. 

Responses 

None. 
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LOGOFF 

Privilege Class: Any 

Use the LOGOFF command to terminate virtual machine execution and 
disconnect your virtual machine from the VM/370 system. This command 
causes all active spool files to be closed, temporary disks to be 
relinquished, dedicated devices to be detached, and an accounting record 
to be created for the user. The format of the LOGOFF command is: 

i 1 

| LOGoff | [HOld] | 

| LCGout | | 

i 1 

where : 

HOLD retains the connection for a switched communication line to 
enable you to logon without redialing the VM/370 system. 

Usage 

You should always logoff and not only turn power off on the terminal. 
Terminal power off is not synonymous with logoff. 

If you turn power off at the terminal instead of logging off, logoff 
occurs by one of the following methods: 

• Remote Typewriter Terminal — Logoff takes place after a 15- minute 
interval has elapsed. This occurs if no attempt is made to power on 
the terminal and re-establish communications with the still logged-on 
virtual machine during this 15-minute period. 

• 1270 Display Terminal — Logoff only takes place 15 minutes after 
VM/370 discovers that the terminal has been turned off (that is, 
VM/370 attempts to send a message to the terminal, but gets back an 
error code indicating that the terminal is turned off) . Because many 
hours may pass before VM/370 discovers that the terminal is turned 
off, you run the risk of compromising the security of the virtual 
machine and data files. Anyone turning the 3270 power back on has 
access to the virtual machine without logging on. This is because 
the machine is still logged on, although inactive. 



Responses 

CONNECT= hh:mm:ss VIRTCPU= mmm:ss.hs T0TCPU= mmm:ss.hs 

w her e : 

CONNECT hh:mm:ss is the actual clock time spent in the current 

terminal session in hours:minutes:seconds. 

VIRTCPU mmm:ss.hs is the virtual CPU time used in the 

current terminal session in 
minutes :seconds. hundredths of seconds. 
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TOTCPU ■■■:ss.hs is the total CPU time (including virtual and 

overhead) used in the current terminal session 
in minutes :seconds. hundredths of seconds. 

These times are either the elapsed tiae for the entire terminal 
session or the elapsed time since the ACHT command was entered for 
this user. 

LOGOPP AT hh:mm:ss zone weekday mm/dd/yy 
is the response for a logoff. 

(GRAF raddr ) 

<LINE raddr > LOGOFF AS userid USERS - nnn 

( DEY rid j 

| is the normal response to the primary system operator. DEV rid 
specifies the resource identification. 

(GRAF raddr) 

<(LIHE raddr > LOGOFF AS userid USERS = nnn FORCED 

I DEV rid j 

is the response to the primary system operator if the logoff is 
forced by a line timeout or a terminal power-off. 
| DEV rid specifies the resource identification. 

USER DSC LOGOFF AS userid USERS = nnn 

is the response to the primary system operator when logoff occurs 
for a user who had previously disconnected using the DISCOHH 
command. 
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LOGON 



Privilege Class: Any 



Use the LOGON command to identify yourself to the VH/370 system and to 
access that system. Upon successful logon, VH/370 creates a virtual 
■achine configuration froi information in the VH/370 directory. The 
LOGON command naie nay not be entered using any line-editing symbols, 
but the operands may use these syibols. See the VH/370: Terminal Dser «s 
Guide for a detailed description of logon procedures. If you use LOGON 
because a teleprocessing line or terminal error disconnected you froi 
your virtual machine, you have 15 minutes to logon again. If you do not 
log on within 15 minutes, your virtual machine automatically logs off. 
In this case, you may have to reconstruct files and restart jobs 
interrupted by the teleprocessing line or terminal error. The format of 
the LOGON command is: 



Logon 
Login 



userid [password] [Bask] [Noipl] 



where: 

userid is the identifier assigned to you in the VH/370 system. 

password is your password. Specify this field if no protection (that 
is, masking characters) is desired. 

HASK types masking characters to cover the password on typewriter 
terminals without the print inhibit feature. The mask types on 
the line following a prompting message from VH/370 reguesting 
you to enter your password. Should you forget to ask for 
masking when you type LOGON, you can press the carriage return 
after the prompt for the password types, and VH/370 then types 
out the masking characters. 

| NOIPL specifies that the IPL device or name in the VH/370 directory 
j should not be used for an automatic IPL. 



ENTEB PASSWORD: 

indicates that the userid has been accepted. You should type in 
the password, or signal a carriage return if a mask is desired for 
the password, and HASK was not included on the command line. 

LOGHSG— hh:mm:ss mm/dd/yy 

indicates the time and date at which the system log message was 
generated or most recently revised. If you wish to see all of the 
system log messages, you must issue the CP command QUERY LOGHSG. 
Any lines of the log message for which the first character is an 
asterisk are displayed at this point. 
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FILES: /nnn) RDR, /nnn) PRT, /nnn) PUN 
| HO / (HO / \HO / 

This Message is oiitted if all counts are zero, otherwise it 
xndxcates the number o*. spooo. j.ix€S tuat exist for you at xcgcn 
tine. 

LOGOH AT hh:mm:ss zone weekday mm/dd/yy 

— or — 

BECOHHECTED AT hh:mm:ss zone weekday mm/dd/yy 

indicates the time, day of the week, and date at which the LOGON or 
RECOHHECT is complete. 

(GRAF raddr ) 

<LIHE raddr > LOGOH AS userid USERS = nnn 

(DEV rid ) 

— or — 

[GRAF raddr ) 

< LIHE raddr > RECOHHECT userid USERS = nnn 

( DEV rid ) 

| is the response to the prinary system operator. DEV rid specifies 
the resource identification. 
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MESSAGE 

Privilege Class: Any 

Use the MESSAGE command to transiit Message text to a specified userid 
or to the primary system operator. If the user designated to receive 
the Message is not logged on or has suppressed the receiving of 
Messages* the Message is not transmitted and the sender receives a 
diagnostic message to this effect. A message which is not received by a 
user is not saved and Must be sent at a later tiMe when the user is 
receiving Messages. The Message is displayed at the terminal when the 
terminal is ready to receive output. If a typewriter terminal (or a 
display terminal having AOTOBEAD set ON) is entering data, the class Any 
message is held until an end-of-line (carriage return or EHTER) signal 
is received. The format of the MESSAGE command is: 



r— 








■ "T 


1 
1 


Message | 
HSG | 


( userid ) 


msgtext 


1 
1 


1 


1 


( operator) 




1 


L— 








_ - . J 




is the identification of the single user who is to receive the 
message. 

* specifies that you are sending a message to yourself. 

OPERATOR sends the message to the primary system operator regardless of 
his userid. 

msgtext is the text of the message which is to be transmitted. As 
many characters may be entered as will fit on the remainder of 
the input line. 



hh:mm:ss 

HSG FROM OPERATOB: msgtext 

is the response received by the user from the system operator. 

hh:mm:ss 

userid f 



HSG FBOH i I0G01xxx\: msgtext 



is the format of the message sent to another user or to the 
system operator, where userid is the name of the sender. If the 
user sending the message is not logged on to VH/370, LOGOH and 
the line number are displayed instead of userid. 



hh:mm:ss 

is the time in hours: minutes: seconds when the message was sent 
to the user. 

If the user receiving the message is the primary system operator, the 
alarm bell at the central computer console rings. 
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NOTREADY 
Privilege Class: G 

Ose the NOTREADY command to cause a virtual device to appear as if it 
had changed froi ready to not ready status. This command is for use with 
spooled unit record devices and virtual consoles only. Any I/O operation 
to the specified device, in progress at the tiie the comiand is issued, 
is completed. On the next Start I/O (SIO) instruction, the not ready 
condition is in effect. The format of the NOTREADY command is: 



| NOTReady | vaddr 



where; 

vaddr is the virtual device address (cuu) of the unit to be removed 
from ready status. 



INVALID DEVICE TYPE 

This is the response if the device specified by vaddr is not a 
spooled unit record device or a virtual console. 
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ORDER 



Privilege Class; G 



Use the ORDER command to place your closed spool files, by device type, 
in a specific order, you can determine via the QUERY command the 
filename, filetype, originating userid, spoolid, and other attributes of 
all of your files. The files are ordered as they are passed to your 
spool device; you nay order only your own files. The format of the ORDER 
command is: 



ORDer 



I ( Reader 
I < Printer 
I ( PUnch 



(CLass d CLass c2...) 4 
\ spoolid 1 spoolid2 . . . J 



^Sequencing can be done with the ORDER command using a combination of 
CLASS and spoolid specifications. For example: 

ORDER PRINTER CLASS A 1963 CLASS C 

specifies that printer files are processed in the following order: 
all class A files, the file with spoolid 1963, and then all class C 
files. 



where: 



READER 
RDR 



orders the reader spool files. 



PRINTER 
PRT 



orders the printer spool files, 



PUNCH 
PCH 



orders the punch spool files. 



CLASS d CLASS c2... 

processes the input and output spool files in the order in 
which their classes are specified. CLASS is a reguired 
reserved word and c1, c2,... are one-character alphameric 
fields (with values from A to Z and from to 9) representing 
the spooling classes. 

spoolid 1 spoolid2... 

processes the files represented by the spoolids in the order 
in which the spoolids are specified. 



Response 



j nnnn ) 
(NO / 



PILES ORDERED 



This response indicates the number of files ordered, 
displayed if you issued the CP SET IHSG OFF command. 



It is not 
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PURGE 

EtiliiS^e Class: G 

Use the PURGE command to remove your own closed spool files from the 
system before they are printed or punched by the spooling devices, or 
before they are read by a user. Any closed file may be purged regardless 
of its status, as long as it has not been selected for processing. The 
format of the PURGE command is: 

PURge | ( r t 

Reader | Class d Class c2... | 

Printer jspoolidl spoolid2... j 

PUnch |ALL I 

| \ALL «- J 

1 Purging may be done using a combination of CLASS and spoolid 
specifications. For example: 

PURGE PRINTER CLASS A 1932 CLASS D 619 

specifies that all Class A and Class D printer files and printer 
files with spoolids 1932 and 619 are to be purged. 

i 1 

where: 

READER purges all reader files. 
RDR 

PRINTER purges all printer spool files. 
PRT 

PUNCH purges all punch spool files. 
PCH 

ALL purges all spool files. When ALL is specified for device type, 
all other operands are ignored. 

CLASS d CLASS c2... 

purges the files of the specified device type and class. CLASS 
is a reguired reserved word and d, c2,... are one-character 
alphameric fields (with values from A to Z and to 9) that 
represent the spooling class. 

spoolidl spoolid2... 

purges only the files for the specified spoolids. 

ALL purges all files of the specified type (reader, printer, or 
punch) . 



Response 



/nnnn\ FILES PURGED 
(NO 



} 



I This response indicates the number of files purged. It is not 
| displayed if you issued the CP SET IMSG command. 
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QUERY 

Privilege Class : G and all classes except class Any 

Use the class G QUERY command to find the status of your system and 
machine configuration. You can request the following types of 
information: 

• Hov much time you have used during a terminal session. 

• Hov many input and output spool files reside on your virtual 
machine. 

• Hov you have set the functions of the SET command. 

• Hov you have set the options of the TERMINAL command. 

• The status of all the devices on your virtual machine. 

| • The channel operating mode of your virtual machine, either 
| block-multiplexer or selector . 

• All users, and their device addresses and access modes, vho are 
linked to a given virtual address. 

• Various kinds of information about your virtual printer, punch, and 
reader. 

There are other operands you can use vith the QUERY command if you 
have the privilege class required to use them. These are described in 
the VH/370: Operator's Guide. Also, if you are a CMS user, you can use 
the CHS QUERY command to query the status of your CHS virtual machine. 

For ease of use, the QUERY command and operands described in this 
section have been separated into the operands available for general 
users (class G) and those available to all users except class Any. 
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QUERY 



The QUERY Command for Class G Users 



The format of the Class G QUERY command is: 



Time 

Set 

TERMinal 



Files [Class c] 



[Virtual] 



Links 

Reader 

Printer 

PUnch 



PF[nn] 



CHANnelsX 

GRAF ■ 

CONsole 

Dasd 

TApes 

LINES 

UR 

STORage 

ALL 

vaddr 

vaddr 
r n 

Ispoolid | 
| ALL | 

|CLass c | 

L J 




where: 
TIME 



displays the current time, time zone, weekday, date, connect 
and CPU time for the current terminal session. 



FILES [CLASS c] 

displays the number of spooled input and output files for your 
virtual machine. Files currently being processed are not 
included in the totals. If CLASS is specified, the number of 
spooled input and output files of the class specified is 
displayed. 



SET 



displays the status of the SET command functions. 



TERMINAL displays the current options in effect for your virtual 
console environment. 

VIRTUAL displays the status of all virtual devices. 

CHANNELS displays the channel mode of operation for the 
virtual machine. 

GRAF displays the status of all your virtual display 
devices that are locally attached. 

CONSOLE displays the status of your virtual consoles. 

DASD displays the status of all ycur virtual direct 
access storage devices. 
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TAPES 

LINES 

UB 

STGBAGE 

ALL 

vaddr 



displays the status of all your virtual magnetic 
tape devices. 



displays the status 
communication lines. 



of 



all your virtual 



displays the status of all your unit record 
devices. 

displays the size of your virtual storage. 

displays the status of all your virtual devices. 

displays the status of the virtual device at address 
vaddr. 



LINKS vaddr 

displays the userid, device address, and access mode at the 
terminal for all users linked to the specified virtual address 
(vaddr) . 



BEADEB 

RDB 

PBINTEB 

PBT 

PUNCH 

PCH 



displays the following information, pertaining to your virtual 
reader, virtual printer, and virtual punch spool files: 

• Userid (of user who created the file) 

• Spool file identification (spoolid) 

• Class and originating device type 

• Number of logical records in the file 

• Number of copies specified for the file (has no effect for 
reader files) 

• File hold status 

One line of information is displayed for each spool file. 



BEADEB 

PBINTEB 

PUNCH 



spoolid 

displays additional information for one spool file. The 
spoolid operand must follow the BEADEB, PBINTEB, or PUNCH 
operand. In addition to the information normally displayed for 
reader, printer, or punch files, the following is also 
displayed: 



Date and time the file was created 
Filename and filetype of file (if any) 
Distribution code of the file (PBINTEB 
only) 



and PUNCH files 



Only one line of data is displayed (that data pertaining to 
the spool file specified by spoolid) . 



FILES 
BEADEB 
PBINTEB, 
PUNCH 



ALL 

displays additional information for spool files. The ALL 
operand must follow the BEADEB, PBINTEB, or PUNCH operand. In 
addition to the information normally displayed for the reader, 
printer, or punch files, the following is also displayed: 
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• Date and tine the file was created 

• Filename and filetype of file (if any) ; if your file was 
assigned a dsnane and you later issue QUERY, only the first 
20 characters of the 24-character field are displayed. 

• Distribution code of the file (PRINTER and PUNCH files 
only) 

One line of information is displayed for each spool file of 
the type specified. 

FILES 

READER 

PRINTER f CLASS c 

PUNCH 

displays the basic information for all spool files of the 
class specified by c. This operand must follow the FILES, 
READER, PRINTER, or PUNCH operands. 

One line of information is displayed for each spool file of 
the specified class. 

PF[nn] displays the 3270 Program Function key number specified, along 
with its associated command lines. If nn is not specified, all 
12 program function keys and their associated data lines are 
displayed. The value, nn, is a number from 1 (or 01) to 12. 
See the CP SET command for an explanation of how to define and 
use program function keys. 



2P.E5I Command Responses for Class G Commands 

This section describes the messages CP prints in response to your 
command. 



QUERY TIME 

TIME IS hh:mm:ss zone weekday mm/dd/yy 

The current real clock time in hours:minutes:seconds, the time zone 
(for example, EST) , the day of the week and the calendar date 
(month/day/year) are displayed. 

C0NNECT= hh:mm:ss VIHTCPU= mmmcss.hs TOTCPU= mmm:ss.hs 

The time spent in the current terminal session is displayed. 

where : 

CONNECT= hh:mm:ss is the actual clock time spent in the current 
terminal session in hours: minutes: seconds. 

VIRTCPU= mmm:ss.hs is the virtual CPU time used in the current 
terminal session in minutes: seconds. hundredths 
of seconds. 

T0TCPU= mmm:ss.hs is the total CPU time (virtual and overhead) 

used in the current terminal session in 
minutes :seconds. hundredths of seconds. 
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QUERY 

QUERY SET 



ON 
OFF 
\ CODE i 



/ON ) /ON ( \CODE( /ON ) /ON ) 

MSG (OFF/, WNG (OFF/, EMSG (TEXT), ACNT (OFF/, RUN (OFF/ 

/ON } ( ON ) JON | /ON ) 

LINEDIT \ OFF}, TIMER ) OFF >, ISAM (OFF/, ECMODE(OFFJ 



REAL 



ON /SVC \ 
(NOSVCJ 
| ASSIST I OFF ), PAGEX 



( "} 

(OFF J 



JON ) 
IMSG (OFF/ 



The settings of all functions controlled by the SET command and the 
VM/370 directory ISAM and ECMODE options are displayed. Refer to 
the discussion of the SET command for explanations of the 
functions. 



QUERY TERMINAL 

LINEND (OFF/, LINEDEL (OFF/, CHARDEL \OFFJ, ESCAPE JOFFJ 

/ON ) /ON 1 /ON ) / CP^ 
LINESIZE nnn, MASK (OFFJ, APL (OFF), ATTN (OFFJ, MODE ( VM / 

The settings of all functions that are controlled by the TERMINAL 
command are displayed. Refer to the discussion of the TERMINAL 
command for explanations of the functions. If LINEDIT is turned 
off, the logical editing symbols displayed are those that were in 
effect before line editing was turned off. 

QUERY FILES [.CLASS cj 

FILES: (nnnl RDR, (nnn) PRT, (nnn) PUN 



: /nnn) RDR, /nnn) PRT, Jnnn| 
(NO J (NO J \N0 / 



The total number of spool files in your system is displayed. If you 
specify the CLASS option with QUERY FILES, only the totals for the 
class you specify are indicated rather than for all classes on your 
system. 

QUERY VIRTUAL CHANNELS 

CHANNELS= 



/SEL) 
(BMX J 



The operating mode of the virtual machine channels is displayed. 
This reponse applies to all of the virtual machine channels except 
channel 0, which is always a byte-multiplexer channel, and any 
channels with virtual or real channel-to-channel adapters, which 
are always selector channels. 
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QUE BY 
fiOEBY VIRTUAL GBAF 

OH BEV 
I HOT BEADY / 

The status of all locally attached virtual display devices defined 
to your virtual Machine is displayed. 

where; 

vaddr is the virtual address to which the device is attached. 

raddr is the real address of the device. 

HOT BEADY shows the status of a virtual display device that has not 
been attached via the DIAL conand. 



QDEBY VIBTOAL COHSOLE 

/GBAF) / TEEM) /STOP ) 
COHS vaddr OH (LIHEJ raddr \ HOTEHH / (STABT / 

i COHT ) ( HOLD ) / BEADY ) 

vaddr CL c \ HOCOHT / ( HOHOLD / COPY nn t*OTHEADYj 

{TO ) 
vaddr (FOB j userid DIST distcode 

For virtual lachine consoles, a three-line response is displayed. 
The first line shows the console status and options and the next 
two lines are the virtual console spooling status. 

where; 

vaddr is the virtual address of the virtual lachine console. 

raddr is the real address of the terminal associated with the 
virtual console. 

| c is the spooling class of the console. 

| nn is the nuiber of copies spooled. 

| userid is the user identification. 

| distcode is the distribution code. 

The other fields indicate the setting of the respective options in 
the SPOOL coiaand. 

The default settings for a virtual console are: 

COHS vaddr OH DBV raddr TEBH STOP 

vaddr CL T HOCOHT HOHOLD COPY 01 BEADY 
vaddr FOB userid DIST distcode 
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QUERY 

QDERY VIRTUAL DASD 

DASD vaddr type volser \H/0/ nnn CIL 

The status of each virtual disk defined for your system is 
displayed. 

where; 

vaddr is the virtual address to which the DASD device is 
attached. 

type is one of the following device types: 

2311 

2305 

2311 

3330 

3340 

231T (2311 at top of 2314) 

231B (2311 at bottom of 2314) 

volser is the volume serial number of the system disk on which 
this virtual disk resides. 

R/W indicates the read/write status of the disk. 
R/0 

nnn is the number of cylinders on the virtual disk. 
fiOJM VIRTDAL TAPES 

TAPE vaddr ON DEV raddr 

The status of each tape defined for your system is displayed. 

where: 

vaddr is the virtual address to which the tape is attached. 

raddr is the real address of the tape. 

QDERY VIRTDAL LINES 

LINE vaddr ON DEV raddr 

The status of all communication lines defined in your virtual 
machine is displayed. 

where: 

vaddr is the virtual address to which the line is attached. 

raddr is the real address of the line. 

JiENABLED ) 
LINE vaddr \DISABLEDj 

The status of virtual communication lines at virtual address vaddr 
is displayed. 
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QUERY 

£2. Ml HMUhk UR 



RDR vaddr C 



i CONTW HOLD)/ EOF W READY) 
L c 1 KOCOHT | \ WOHOLD j ( HOEOF J \ NOTREADY J 



| The status of all the virtual readers attached to your virtual 
j machine is displayed. 

where : 

vaddr is the virtual device address of the virtual reader. 

c is the spool file class which the device services. A 
class of * indicates the device serves all classes of 
spool files for input. 

The other fields indicate the setting of the respective options in 
the SPOOL command. 

The default settings for a reader are: 

RDR vaddr CL * HOCOHT HOHOLD READY EOF 

/PRT) / CONTW HOLD) ( READY) 

(PUS/ vaddr CL c \HOCONT} \'IOHOLE/ COPY nn \NOTREADY / 

(TO ) 
vaddr \FORj userxd DIST distcode 

| The status of all the virtual printers and punches attached to your 
| virtual machine is displayed. 

where; 

vaddr is the virtual device address of the virtual printer or 
punch. 

c is the output class assigned to spool files produced from 
the device. 

nn is the number of copies of each output file to be 
produced. 

TO userid indicates that the output from the device, when closed, 
becomes a reader input spool file for the indicated 
userid. 

FOR userid 

indicates the userid identification (spool file owner) 
assigned to spool files produced from the device. 

distcode is the distribution code assigned to each spool file 
produced from the device. 

Mote; The distcode in this case indicates the FOR userid; however, 
the distcode produced on the output files when the file is closed 
is the distcode assigned to the FOR userid as specified in the 
VM/370 directory. 

The other fields indicate the setting of the respective options in 
the SPOOL command. 
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QUERY 

The default settings are: 

/PRT ) 

\PUNj vaddr CL A NOCONT NOHOLD COPY READY 01 
vaddr FOR userid DIST distcode 

where: 

userid and distcode are assigned for the virtual machine. 

QUERY VIRTUAL STORAGE 

STORAGE = nnnnnK 

The size of the virtual Machine in Multiples of 1024 bytes is 
displayed. 

QUERY VIRTUAL ALL 

Has the same effect as if all the following coniands were issued: 

QUERY VIRTUAL STORAGE 

QUERY VIRTUAL LINES 

QUERY VIRTUAL TAPE 

QUERY VIRTUAL UR 

QUERY VIRTUAL DASD 

QUERY VIRTUAL GRAF 

QUERY VIRTUAL CONSOLE 

QUERY VIRTUAL CHANNELS 

J20ERY VIRTUAL vaddr 

The response is in the same form as QUERY VIRTUAL DASD, TAPES, LINES, or 
UR, depending on virtual device type. 

QUERY LINKS vaddr 

userid vaddr jR/O), ... 
. \ R/M J 



A list of users who linked to the device at virtual address vaddr 
is displayed. 

where: 

userid is the identification of the user who originated the 
link. 

vaddr is the virtual address by which the user (userid) refers 
to the device. 

R/O is the type of access the user (userid) has to the 
R/N device. 
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QUERY 

O.UERY MhMi* fifllll gglHTBg, QUERY PUNCH 

r t 

ORIGINID FILE CLASS RECDS CPY HOLD |DATE TIME NAME TYPE DIST | 

1 userid spoolid c typ norecs nn stat |mm/dd hh:mm:ss fn ft distcodel 

L J 



where ; 

userid is the user who originally created the file. 

| spoolid is a unique, system-assigned number which is used by VM/370 to 
j identify the file. 

c is the spool file class. 

typ is the originating device type (PRT, PUN, CON, or RDR) . 

norecs is the number of logical records contained in the file. 

nn is the number of copies assigned to the file (it has no effect 
for virtual reader files) • 

stat is the file hold status: NONE (no hold), USER (user hold), SYS 
(system hold), or USYS (system and user hold). 

mm/dd is the date the file was created in month/day. 

hh:mm:ss is the time of file creation in hours: minutes: seconds. 

fn is the filename assigned to the file (if any) . 

ft is the filetype assigned to the file (if any) . 

distcode is the distribution code assigned to the file. 

Ihen you issue QUERY READER, QUERY PRINTER, or QUERY PUNCH commands, 
CP responds by listing (in the form described) all the files associated 
with your virtual reader, printer, or punch. 

The information listing DATE, TIHE, NAME, TYPE, and DIST (date of 
file creation, time of file creation, name of file, filetype of file, 
and file distribution code) is displayed only when you specify the ALL 
or spoolid operands. 

QUERY PFnn 



(IHHED 



} 



PFnn (DELAY J pfdatal... 

The program function defined for a program function key is 
displayed. If there is no function defined for the program 
function key, this message is generated in the user input area of 
the screen: 

PFnn UNDEFINED 

| No te: If the next command you enter is shorter than this message, 
j you must first clear the input area or enter enough blanks to 
I eliminate the message; otherwise, errors result. 
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QOEBY 

QUERY Command for AH Classes of Users (Except Class Any) 

| Use this fori of the QUERY command to: 

| • Display the log messages. 

| • List all the users that are logged on. 

I • Display the number of users that are logged on or dialed to VH/370. 

This fori of the QUERY command is for all classes of users except those 
in the Any category. The format for this QUERY command is: 

i « 

| Query | I LOGmsg \ | 

I I J Names ( | 

j | J Users [userid] f | 

I | ' userid J I 
i 1 

where: 

LOGMSG displays the log messages of the day. 

NAMES displays a list of all the users logged on and the real 

address of the line to which each is connected. If a user 

is disconnected, DSC is printed instead of the line 
address. 

USERS displays the number of logged on users and the number of 
users logically connected to other virtual machines. 

USERS userid displays the user identification and the terminal device 

userid address of the specified user if he is logged on. If the 

user is not logged on, a message to this effect is issued. 

Use the QUERY USERS userid format if the userid is the same 

as an operand of the QUERY command (for example, TAPES) . 



QUERY Command Responses for All Classes of Commands 
OJJERY LOGMSG 

* logmsg text line 1 

* logmsg text line n 

All lines (both those with an asterisk and without) in the log 
message file are displayed. 

QUERY NAMES 
userid — 



userid — 



J DSC \ § ... 

(raddrj 

/DSC ), ... 
traddrj 
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QUERY 

A list of all logged—on users is displayed; if the user is 

currently connected, the real address to which he is connected is 

displayed (raddr) ; if he is not connected to the system, DSC is 
displayed. 



QUERY USERS 

nnn USERS, mmm DIALED 

The number of users logged on and dialed to VM/370 is displayed. 

where : 

nnn is the total number of logged— on users. 

mmm is the total number of users attached via DIAL to virtual 
machines. 

Rote; DIALED means the line is not available to CP because it is 
logically attached to a multiple— access virtual machine and is a 
part of that user's virtual machine operation. 



QU ERY userid or QUERY USERS userid 



userid — raddr 



The real address (raddr) to which the specified user is connected 
is displayed. 
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READY 

READY 

Privilege Class: G 

Ose the READY command to set a device-end interrupt pending for the 
specified virtual device. The status of the virtual machine is 
unchanged. Other than having a device-end interrupt pending, the virtual 
device is unchanged. The format of the READY command is: 



i ■ ' ■ 1 

| READY | vaddr I 

i i 



w her e : 

vaddr is a virtual device address (cuu) . 

Responses 
None. 
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REQUEST 

REQUEST 

Privilege Class: G 

Use the REQUEST command to make an attention interrupt pending at your 
virtual console. The format of the REQUEST command is: 



i -^-_ 1 

j Kjsyuest j | 

l 1 



The ATTN command performs the same functions as REQUEST and the two 
commands can be used interchangeably. 



Responses 



None. 
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RESET 

Privilege Class; G 

Use the RESET coaaand to clear all pending interrupts froa the specified 
virtual device. In addition, all error conditions occurring as a result 
of unit checks and virtual sense bytes are reset. The foraat of the 
RESET coaaand is: 



| RESET | vaddr I 

i . _ - i 



where: 

vaddr is a virtual device address (cuu) of the device to be reset. 

Responses 
DEVICE RESET 
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REWIND 

REWIND 

Privilege Class : G 

Use the REWIND command to rewind (but not unload) a real tape unit 
attached to your virtual machine at a specific virtual device address. 
This accomplishes the manual operation of rewinding and making the tape 
ready at the tape unit. The format of the REWIND command is: 



I REWind \ vaddr 
i 



where : 

vaddr is the virtual device address (cuu) of the tape unit to be 
rewound. 



Responses 

REWIND COMPLETE 

This is the normal response. 

REWIND NOT EERFORMED 

This is the response you receive if the real tape unit is not 
ready. 
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SET 



SET 



E£ilil§36 Class : G 



Use the SET command to control various functions within your virtual 
system. The format of the SET command is: 



SET 



ACNT 

MSG 

WNG 

IMSG 

BUM 

LINEDit 

ECmode 

ISAM 

NOTBans 

PAGEX 

EHSG 



TIMES 



JON > 
(OFF/ 




(ON 
\ OFF 
(BEAL 



r t r t 

ASsist \ I ON | | SVC | 

| | |NOSVC| 

L J L J 

OFF 



r t 

PFnn |IMMed | [ pf data 1#pfdata2# . 

L J 

PFnn [TAB n1 n2 ... ] 
PFnn COPY [resid] 



,pf datan ] 



where: 
ACNT 



{ON | 
\OFFJ 



MSG /ON ) 
\ OFF/ 



HNG 



|on 1 

(OFF/ 



controls whether accounting information is displayed at 
the terminal or not (ON and OFF respectively) when the 
operator issues the CP ACNT command. When you log on 
VM/37Q, ACNT is set on. 

controls whether messages sent by the MSG command from 
other users are to be received at the terminal. If ON is 
specified, the messages are displayed. OFF specifies 
that no messages are received. When you log on VM/370, 
MSG is set on. 

controls whether warning messages are displayed at the 
terminal. If ON is specified, all warning messages sent 
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SET 



via the CP WARNING command from the system operator are 

received at the terminal. If OFF is specified, no 

warning messages are received. When you log on VM/370, 
WNG is set on. 



IMSG (ON ) controls whether certain informational responses issued 
\0FFJ by the CP CHANGE, DEFINE, DETACH, ORDER, PURGE, and 
TRANSFER commands are displayed at the terminal or not. 
The descriptions of these CP commands tell which 
responses are affected. If ON is specified the 
informational responses are displayed. If OFF is 
specified, they are not. The SET IMSG ON or OFF command 
line has no effect on the handling of error messages set 
by the SET EMSG command. When you log en VM/370, IMSG is 
set on. 



RUN ( ON ) controls whether the virtual machine stops when the 
\OFFJ Attention key is pressed. ON allows you to activate the 
Attention key (causing a read of a CP command) without 
stopping your virtual machine. When the CP command is 
entered, it is immediately executed and the virtual 
machine resumes execution. OFF places the virtual 
machine in the normal CP environment, so that when the 
Attention key is pressed, the virtual machine stops. 
When you log on VM/370, RUN is set off. 



LINEDIT 



{ON ) 
\ OFF/ 



controls the line editing functions. ON specifies that 
the line editing functions and the symbols of the VM/370 
system are to be used to edit virtual CPU console input 
requests. This establishes line editing features in 
systems that do not normally provide them. OFF specifies 
that no character or line editing is to be used for the 
virtual machine operating system. When you log on 
VM/370, LINEDIT is set on. 



ECMODE 



(ON ) 

\ off/ 



controls whether the virtual machine operating 
system may use System/370 extended control mode and 
control registers 1 through 15. Control register zero may 
be used with ECMODE either ON or OFF. When you log on 
VM/370, ECMODE is set according to the user's directory 
option; ON if ECMODE was specified and OFF if not. 

Note; Execution of the SET ECMODE {0N|0FF} command always 
causes a virtual system reset. 



ISAM ( ON ) controls whether additional checking is performed 
I OFFJ on virtual I/O requests to DASD in order to support the 
use of the OS Indexed Sequential Access Method (ISAM) . 
When you log on VM/370, ISAM is set according to the 
user's directory options; ON if ISAM was specified and 
OFF if not. 



NOTRANS 



(ON ) 
(OFF/ 



controls CCW translation for CP. NOTRANS can be 
specified only by a virtual machine that occupies the 
virtual=real space. It causes all virtual I/O from the 
issuing virtual machine to bypass the CP CCW 
translation. To be in effect in the virtual=real 
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environment, SET NOTRANS ON must be issued after the 
virtual=real machine is loaded via the IPL command. (IPL 
sets the NOTRANS option to an OFF condition.) 

PAGEX |0N ) controls the pseudo page fault portion of the 
(OFF) VM/VS Handshaking feature. PAGEX ON or OFF should only be 
issued for an 0S/VS1 virtual machine that has the VM/VS 
Handshaking feature active. It can only be specified for 
a virtual machine that has the extended control mode 
(ECMODE) option. PAGEX ON sets on the pseudo page fault 
portion of handshaking; PAGEX OFF sets it off. Shen you 
log on to VM/370, PAGEX is set OFF. 

EMSG (ON } controls error message handling. ON specifies that both 
the error code and text are displayed at the terminal. 
TEXT specifies that only text is displayed. CODE 
specifies that only the error code be displayed. OFF 
specifies that no error message is to be displayed. When 
you log on VM/370, EMSG is set to TEXT. 

Note, CMS recognizes EMSG settings for all error (E) , 
information (I) , and warning (H) messages, but ignores 
the EMSG setting and displays the complete message (error 
code and text) for all response (R) , severe error (S) , 
and terminal (T) messages. 

TIMER ( ON ) controls the virtual timer. ON specifies that the 
OFF > virtual timer is to be updated only when the virtual CPU 
REAL ) is running. OFF specifies that the virtual timer is not 
be updated. REAL specifies that the virtual timer is to 
be updated during virtual CPU run time and also during 
virtual wait time. If the REALTIMER option is specified 
in your VM/370 directory entry, TIMER is set to REAL when 
you leg on; otherwise it is set to ON when you log on. 




r i r t 

ASSIST \ |CN | | SVC | 

| | |NOSVC| 

L J L J 



OFF 



controls the availability of the virtual machine assist 
feature for your virtual machine. The assist feature is 
available to your virtual machine when you log on if (1) 
the real CPU has the feature installed and (2) the system 
operator has not turned the feature off. The SVC handling 
portion of the assist feature is invoked when you log on 
unless your VM/370 directory entry has the SVCOFF option. 
Issue the QUERY SET command line to see if the assist 
feature is activated and whether the assist feature or 
VM/370 is handling SVC interrupts. 

All SVC 76 requests are passed to CP for handling, 
regardless of the SVC and NOSVC operands. 

If you issue the SET ASSIST command line and specify SVC 
or NOSVC while the virtual machine assist feature is 
turned off, the appropriate bits are set. Later, if the 
feature is turned on again, the operand you specified 
while it was off becomes effective. 
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SET 



OH sets the assist feature on for the virtual machine; 
OFF turns it off. SVC specifies that the assist feature 
handles all SVC interrupts except SVC 76 for the virtual 
machine; NOSVC means VM/370 handles the SVC interrupts. 
See the VM/370: System Programmers Guide for information 
on how to use the assist feature. 



r t 
PFnn |IMMED | [pfdata1#pfdata2#. . .pf datan ] 
IDELAYED | 

L J 

defines a program function for a program function key on 
a 3277 Display Station and indicates when that function 
is to be executed. See the VM/370: Terminal Osgr^s Guide 
for a description of how to use the 3277 program function 
keys. 

The value, nn, is a number from 1 (or 01) to 12 that 
corresponds to a key on a 3277. The program function is a 
"function", or programming capability, you create by 
defining a series of VM/370 commands or data you want 
executed. This series of commands executes when you press 
the appropriate program function key. 

IMMED specifes that the program function is executed 
immediately after you press the program function key. 

DELAYED specifies that execution of the program function 
is delayed for a display terminal. When the program 
function is entered, it is displayed in the input area 
and not executed until you press the Enter key. DELAYED 
is the default value for display terminals. 

pfdata1tpfdata2#. . .pf datan defines the VM/370 command or 
data lines that constitute the program function. If more 
than one command line is to be entered, the pound sign 
(#) must separate the lines. If you use the pound sign 
(#) to separate commands that you want executed with the 
designated PF key, you must precede the command line with 
#CP, turn line editing off, or precede each pound sign 
with the logical escape character (") . For further 
explanation, see the "Examples of Setting Program 
Function Keys" section that follows. If no command lines 
are entered, PFnn is a null command. Program functions 
cannot be embedded within one another. 

specifies a program function number to be associated with 
tab settings on a terminal. The number of the PF key, nn, 
can be a value from 1 (or 01) to 12. See the VM/370: 
EDI! Guide for examples of how this feature is used. 

TAB is a keyword identifying the tab setting function. 
The tab settings may be entered in any order. 

PFnn COPY [resid] 

specifies that the program function key, numbered nn, 
performs a COPY function for a remote 3270 terminal, nn 
must be a value of 1 or 01 to 12. The COPY function 
produces a printed output of the entire screen display at 
the time the PF key is actuated. The output is printed on 
an IBM 3284, 3286 or 3288 printer connected to the same 
control unit as your display terminal. 
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The resid operand may be specified if more than one 
printer is connected to the same control unit as your 
display terminal. It is a three-character hexadecimal 
resource identification number assigned to a specific 
printer. If resid is entered, the printed copy is 
directed to a specific printer; if not, the copy is 
printed on the printer with the lowest resid number. The 
resid numbers of the printers available to your display 
terminal can be obtained from your system operator. If 
only one printer is available, resid need not be 
specified. 

If the command is invalid or if the designated or default 
printer is not free (other display terminals may be using 
it) or is not connected to the same control unit as your 
display terminal, a HOT ACCEPTED message appears on the 
screen, If the printer was busy, retry the operation 
until the printer honors your reguest. 

You may include your own identification on the printed 
output by entering the data into the user input area of 
the screen before you press the PF key. The 
identification appears in the lower left of the printed 
copy. 



JxjIIEiisS °J Setting Program Function Ke_ys 

This example shows you how the SET PFnn command is processed if you do 
not turn line editing off or use the logical escape character. 

Enter one of the following commands while in CMS mode: 

SET PF02 IMMED Q EDB#Q PTR#Q PUN 

— or — 

CP SET PF02 IMMED Q RDR#Q PTRtQ PON 

Now press the ENTER key: 

1. The ENTER key causes immediate execution, 

2. Only the Q PTR and Q PON commands execute, and 

3. Q PTR and Q PON are stripped from the PF02 key assignment leaving Q 
RDR, which was not executed. 

The following examples demonstrate two methods for avoiding the 
problem. 
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SET 

Example Jl 

Enter one of the following commands while in CMS mode: 
#CP SET PF02 IMBED Q RDR#Q PTR#Q PON 

CP SET PF02 IMMED Q RDR"#Q PTR"#Q PUN 

— or — 
SET PF02 IMMED Q RDR"#Q PTR"#Q PUN 

Now press the ENTER key. 

it 
CP assigns the three QUERY commands as functions of the PF02 key. 

Pressing the PF02 key executes the three QUERY commands. 

Example 2 

Enter the following command while in CMS mode: 

SET LIHEDIT OFF 
and press the ENTER key. 
Then enter: 

SET PF02 IMMED Q RDRtQ PTR#Q PUN 
— or — 

CP SET PF02 IMMED Q RDR#Q PTR#Q PUN 
and press the ENTER key. 

CP assigns the three QUERY commands as functions of the PF02 key. 

Then enter: 

SET LINEDIT ON 
and press the ENTER key. 

Pressing the PF02 key executes the three QUERY commands. 

Response 

* PFnn UNDEFINED 

This response appears in the user area of the screen on a 3277 
Display Station if a PF key that is undefined is pressed. 
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SLEEP 



QI FFP 



E£iXii§3§ Class: Any 

Use the SLEEP command to place the virtual machine in a dormant state 
but allow messages to be displayed. The virtual machine does not run 
during this time, but connection time is still being counted. You can 
specify a sleep interval in the command line and the virtual machine is 
awakened automatically when the specified interval has elapsed. Awaken 
the terminal at anytime by signalling attention. In either case, this 
returns the virtual machine to the environment from which SLEEP was 
issued. If no interval is specified, the virtual machine remains 
dormant until awakened by signalling attention. The format of the SLEEP 
command is: 



I r r n 

I I |SEC|| 

SLeep | |nn |HIH|| 

I I |HRs|| 

I L L JJ 



where : 
r r m 
I |SEC|| 
|nn | MIN| | 
I |HRs|| 

L L JJ 

indicates the actual number of seconds, minutes, or hours of actual 
CPU time to sleep. The value nn can be any decimal number from 00 
through 99. If you specify no time unit, the value of nn is taken 
to be minutes. 

Us age : 

If you issue the SLEEP command from a CP read or from a VM read using 
the CP "escape" function (#CP SLEEP) , the end of the time interval or 
signalling attention returns you to the CP environment. 

If you issue the SLEEP command while in virtual machine mode (for 
| example, CMS execution of the command line CP SLEEP) , the end of the 
| time interval or signalling attention returns your terminal to virtual 
| machine mode without entering the CP environment. 

| The SLEEP command, with the time interval, is a convenient way to 
| delay or schedule the execution of certain jobs that could be run more 
| efficiently at a later time; for example, second shift. 



Responses 



None. 
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SPOOL 

Privilege Class: G 



Use the SPOOL command to modify the spooling control options in effect 

for a given virtual spooling device or for a group of devices. The 

SPOOL command can also initialize or stop the spooling of virtual 
console input and output. 

You can direct a file to a remote location by using the SPOOL command 
in conjunction with the TAG command. The section "Transmitting Files to 
Remote Locations" which follows discusses the form cf the SPOOL command 
you use to spool files across the Remote Spooling Communications 
Subsystem (RSCS) . 

Unless otherwise set, the following options are default values for 
spool files: 



Spool File 
Reader 



Printer 
Punch 

Console 



Options 

NOHOLD, NOCONT, EOF, CLASS * as specified in the 

VM/370 directory entry 

OFF, NOHOLD, NOCONT, COPY 01, CLASS as specified 
in the VM/370 directory entry 

NOHOLD, NOCONT, TERM, OFF, CLASS T, COPY 01 



The format of the SPOOL command is: 



SPool 



(Reader ) 
\vaddr j 



Printer 

PUnch 

vaddr 



r 
ICLass 



m 



i r i r i r t 
| |CONt | |H0ld | | EOF | 
| |N0Cont| |NOHold| |N0Eof| 



rr t r nr i r t 

| |To ||userid | | |H0ld | |C0Nt | U 

| 1 For | | * | | |N0Hold| |NOCont|[CLass c] [COpy nn ] 

| •- -MSYSTEM ||L J «- J 



| OFF 

L 

r t 

ICLOSE | 
| PURGE | 

L J 



CONsole) I |STArt| |HOld | |CONt | |TErm | |[To] userid| 
vaddr J \ | STOp | |N0Hold| |N0Cont| |N0TErm| | OFF 



[CLass c] [COpy nn ] 



r n 

|CL0SE| 
| PURGE | 

L J 



*At least one of the options within braces must be selected; however, 
more than one may be specified, and they may be entered in any order. 
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where; 

READER modifies the options for all reader spool files. 
RDR 



PRIHTER 
PRT 



modifies the options for all printer spool files, 



PUNCH 
PCH 



modifies the options for all punch spool devices. 



CONSOLE 



vaddr 



modifies the options for the virtual console spool file and/or 
initiates or stops the spooling of virtual console input and 
output, including CP input/output. 

is the device address (cuu) of the virtual unit record device 
or console whose options are to be modified. 



CLASS 



specifies the spool class of the device. 



The 



( *{ is a one-character alphameric field whose values can be 
through Z, 1 through 9, or * (asterisk) . 



Unless your virtual reader class is asterisk (*) , you must 
ensure that any files to be read by your virtual reader are of 
the same spool class as your virtual reader. The * is the 
universal class; if your virtual reader is class *, it can 
read any file, regardless of class. 

CONT ignores intermediate end-of-file indicators or CLOSE 
reguests. For virtual readers, reading is continuous with all 
end-of-file indicators ignored until all files spooled to the 
virtual machine are read in. If this option is not in effect, 
a unit exception is reflected to the virtual machine at the 
end of each spooled file. CONT specified for the punch or 
printer causes all CLOSE reguests to be ignored until reset by 
NOCONT. If CONT is specified, NOCONT cannot be specified. 

CONT specifies that reading is to continue without intervening 
end-of-file indications until all files in the system that 
belong to the user are read. If CONT is not in effect or is 
reset by specification of NOCONT, an end-of-file indication is 
reflected to the virtual machine at the end of each SPOOL file 
in the system. The nature of the end-of-file indication to be 
reflected is set by the EOF and NOEOF options. If the EOF 
option is in effect, end-of-file is signaled by a unit 
exception: this corresponds to pressing the end-of-file 
button on a real card reader. If NOEOF is in effect for a 
virtual reader, end-of-file is signaled by the reflection of a 
unit check/intervention reguired status. 

NOCONT resets the continuous spooling option. If NOCONT is specified, 
CONT cannot be specified. 

HOLD places all files created by the specified device in a user 
HOLD status. For READER files, this option specifies that 
input files for the specified reader are not deleted from the 
system after they are read. The status of all files must be 
changed by the CHANGE command. The status of output devices is 
changed by the SPOOL command. If HOLD is specified, NOHOLD 
cannot be specified. 
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NOHOLD 



If the HOLD option is specified for a virtual printer or punch 
that is transferred to a user for input (TO userid) , that 
virtual device places a user BOLD status on the reader file. 
The user receiving the file cannot read its status until it is 
changed by issuing the CHANGE command with the NOHOLD operand. 
The spool file class of the virtual output device must match 
the class of the receiver 1 s virtual reader (or the virtual 
reader must have a class of *) in order for the spool file to 
be processed. If these conditions are not satisfied, the 
reader appears empty to the virtual machine attempting to read 
a file, even though reader files do exist. 

If a virtual reader is operating with CONT and HOLD, then 
virtual reader files are saved and placed in a user HOLD 
status. The file cannot be read until it is changed (using 
the CHANGE command) to a NOHOLD status. 

resets the HOLD operand. Future files are not held. NOHOLD 
resets the HOLD operand in effect for the specified reader. 
This operand can be overridden for an active file being closed 
by the CLOSE command using the HOLD or NOHOLD operand. If 
NOHOLD is specified, HOLD may not be specified. 



EOF sets a virtual end-of-file condition on the specified reader, 
thereby ensuring that a unit exception condition is reflected 
on the read that follows the reading of the last card in a 
file. If EOF is specified, NOEOF may not be specified. 

NOEOF specifies that the reading continues to physical end-of-file. 
The virtual reader stops when no cards are left in the reader 
and when a unit check/intervention reguired status is 
pending. If NOEOF is specified EOF may not be specified. 

[TO] userid 

SYSTEM 

transfers the output of the virtual device to the virtual card 

reader of the specified userid. If TO is omitted, the userid 

may not be TO or T. TO * may be coded if the output is to be 

transferred to your own virtual card reader. If TO userid is 

specified, neither OFF nor FOR may be specified on the same 
command line. 

If you specify COPT with TO userid, the number of copies you 
specify has no effect on the receiver of the spool file; he 
receives only one copy. However, if OFF or FOB are specified 
on a subsequent command, the receiver of your spool file 
receives the number of copies you specify via COPY. For 
example, if the following command is entered: 

SPOOL PON TO OSEBA COPY 3 CLASS B 

the COPY operand has no effect on the file going to DSERA. 
Bowever, if the command: 

SPOOL PON OFF 

is entered following the first command, the COPY 3 specified 
in the first statement effects the second command. 

TO SYSTEM is equivalent to specifying OFF and resets the 
transferred spool option. 
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[FOR] userid 

indicates the userid under which printed or punched output is 
produced. The userid becomes the owner cf the output spool 
file and the distcode on the file is the distcode for the user 
that is specified in the VM/370 directory. The file is not 
transferred to the user's reader input. The default setting is 
for your own virtual machine identification. FOR *, or FOR 
SYSTEM can be coded to specify your own identification and is 
equivalent to the OFF option. 



OFF 



resets the transferred spool option. 



COPY nn is the number of copies that are to be printed or punched when 
the file is spooled to the real unit record equipment. This 
operand is valid only for output files; the number of copies, 
nn must be between 1 and 99 (leading zeros need not be 
specified) . 

CLOSE closes the specified device regardless of the CONT setting for 
the device. If CLOSE is specified, PURGE may not be 
specified. CLOSE does not affect the setting of any other 
operand and is provided as a convenience to close a virtual 
output device. As an example, this sequence of commands: 



SPOOL 


PRT 


COHT 


(print 


file) 


(print 


file) 


(print 


file) 


SPOOL 


PRT 


HOCOHT 


CLOSE 


PRT 


I 


SPOOL 


PRT 


COHT 


(print 


file) 


(print 


file) 



can be replaced with the following sequence to 
desired result: 



achieve the 



SPOOL PRT COHT 
(print file) 
(print file) 
(print file) 

SPOOL PRT CLOSE 
(print file) 
(print file) 



| PURGE closes and purges the spool file from the specified virtual 
output device regardless of the COHT setting for the device. 
If PURGE is specified, CLOSE cannot be specified. PURGE does 
not affect the setting of any other operand and is equivalent 
to issuing the CLOSE command for a device (or type of device) 
with the PURGE operand. This form of the SPOOL command is 
provided for your convenience. 

START places all console input and output in a spool file. Until a 
CLOSE is issued for the console, characteristics of the 
console spool file may be changed by use of the SPOOL COHSOLE 
command. After the console is closed, the file becomes a 
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printer spool file whose characteristics can 
issuing the CHARGE PRINTER command. 



be changed by 



STOP terminates the spooling of console input and output. The 
command SPOOL CONSOLE STOP does not close the console spool 
file. 

TERN displays the virtual console input and output at the terminal 
in addition to placing it in a spool file. The TERM operand 
has no effect until the START operand is specified. 

| NOTERM suppresses the display of console input and output of a system 
| running in a virtual machine. The display cf console input and 

| output of CP console functions, entered from CP mode, are not 

| suppressed. The NOTERM operand has no effect until the START 

operand is specified. 



The Spoolid Number: A Unigue Identifier for Your Spool Files 

Once you close a spool file by issuing the CMS PRINT or PUNCH command or 
the CP CLOSE command, CP assigns the spool file a number between 1 and 
9900. This number is called the spoolid (spool file identification) for 
the file. It can be used as a convenient way to uniguely identify the 
file. It can also be used when you are manipulating the file with VM/370 
spooling commands such as ORDER, CHANGE or CLOSE. 

Spoolids are assigned to all your spool files seguentially . Nhen the 
maximum number (9900) is assigned, CP begins again with the number 1. 

When you print or punch a file, CP displays at your terminal the 
spoolid it assigned to your file. You can find out various kinds of 
information about a file using the spoolid with the many forms of the 
QUERY command. 



Transmitting Files to Remote Locations 



To direct files to remote stations, use the CP TAG and SPOOL commands in 
conjunction with a command that causes the file to be closed and sent to 
a virtual device (for example, a virtual printer or punch) . Use the TAG 
command to specify the device to be spooled and to associate with that 
device the location identifier for the destination of the file: 

TAG DEV device locid 

where device is the virtual device type (for example, PRINTER or PUNCH) 
or virtual device address (vaddr) and locid is the name of the 
destination to which the file is to be transmitted. 

Use the SPOOL command to specify that output to the device specified 
in the command is to be sent to the RSCS virtual machine, which performs 
the actual transmission of the file: 

SPOOL device TO userid 

where device is the same virtual device type or virtual device address 
specified in the TAG command and userid is the userid of the RSCS 
virtual machine at your installation. You can find out the userid of 
your installation's RSCS virtual machine and the locid for the various 
remote stations from your installations's system programmer. 
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| After you issue the TAG and SPOOL commands, use a command (such as 
| the CMS PRIST or PUNCH command or the CP CLOSE command) to cause the 
| spool file to be generated, closed, and spooled to the specified virtual 

| The following example shows how to use these three commands to 
I transmit a CHS file to a remote location: 

| TAG DEV PUNCH CAMBRIDG 

| SPOOL POHCH TO HET 

| PUNCH MYPROG ASSEMBLE 

| The TAG command defines the type of file to be transmitted, a punch 
i file, and the remote station to which you want it transmitted, 
I CAMBRIDG. NET is the userid of the virtual machine controlling the RSCS 
| network: you direct your file to that virtual machine with the SPOOL 
I command. The PUNCH command causes the file MYPROG ASSEMBLE to be 
| punched on your virtual machine card punch, closed, and then spooled to 
I the virtual reader of the RSCS virtual machine, which you specified in 
| the SPOOL command. The RSCS virtual machine then processes your file 
| (now a VM/370 spool file) and transmits it across the RSCS network. 



I Receiving Iil§§ from the RSCS Network 

| If your virtual machine is logged on VM/370, RSCs notifies you of the 
I arrival of a file for your machine from the RSCS network by displaying a 
| message at your terminal. The file is sent to your virtual card reader. 

I VM/370 can accumulate files from the RSCS network destined for your 
| virtual card reader, regardless of whether you are logged on your 
| virtual machine or not. If you are logged on your virtual machine, 
| issue the QUERY command to see if you have any files in your virtual 
| reader. When you log on your virtual machine, the logon process 
| transmits a message informing you of accumulated spool files residing in 
| your virtual reader (punch or printer) . 



Responses 



None. 
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Privilege Class: G 



Use the STOBE command to alter the contents of specified registers and 
locations of the virtual machine. The contents of the following can be 
altered: 



Virtual storage locations 
General registers 
Floating-point registers 
Control registers (if available) 
Program status word 



The STOBE command can also save virtual machine data in low storage. 

The operands may be combined in any order desired, separated by one 
or more blanks, for up to one full line of input. If an invalid operand 
is encountered, an error message is issued and the store function is 
terminated. However, all valid operands entered, before the invalid 
one, are processed properly. 

Storage locations, registers, the PSI, and status can be stored using 
a single command line. When you combine the operands for storing into 
storage, registers, the PSH, or the status area on a single command 
line, all operands must be specified; default values do not apply in 
this case. 

The format of the STOBE command is: 



STore I , hexloc 

Lhexloc hexwordl [ hexword2. . . ] 

Shexloc hexdata... 

i Greg \ 

Yreg > hexwordl [ hexword2. . . ] 
LXreg ) 

Psw [hexwordl] hexword2 

STATUS 



where: 

hexloc 
Lhexloc 



hexwordl [hexword2. . . ] 
stores the specified data (hexwordl [ hexword2. . . ]) in 
successive fullword locations starting at the address 
specified by hexloc. The smallest group of hexadecimal values 
that can be stored using this form is one fullword. Alignment 
is made to the nearest fullword boundary. Either form (hexloc 
or Lhexloc) can be used. 

The operands (hexwordl hexword2...) each represent up to eight 
hexadecimal digits. If the value being stored is less than a 
fullword (eight hexadecimal digits) , it is right-adjusted in 
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the word and the high order bytes of the word are filled with 
zeros. If two or nore hexwords are specified, they must be 
separated by one or more blanks. 

Shexloc hexdata ... 

stores the data specified (hexdata...) in the address 
specified by hexloc, without word alignment. The shortest 
string that can be stored is one byte (two hexadecimal 
digits). If the string contains an odd number of characters, 
the last character is not stored, an error message is sent, 
and the function is terminated. 

The operand, hexdata, is a string of two or more hexadecimal 
digits with no embedded blanks. 

Greg hexwordl [ hexword2. . . ] 

stores the hexadecimal data (hexwordl [hexword2. . . ]) in 
successive general registers starting at the register 
specified by reg. The reg operand must be either a decimal 
number from 0—15 or a hexadecimal digit from 0-F. 

The operands (hexwordl [ hexword2. . . ]) each represent up to 
eight hexadecimal digits. If less than eight digits are 
specified, the string is right justified in a fullword and 
left— filled with zeros, if two or more hexwords are specified, 
they must be separated by one or more blanks. 

Yreg hexwordl [hexword2. .. ] 

stores the hexadecimal data (hexwordl [ hexword2. . . ]) in 
successive floating— point registers starting at the register 
specified by reg. The reg operand must be a digit from 0-6. 
If reg is an odd number, it is adjusted to the preceding even 
number. 

The operands (hexwordl [ hexword2. . . ] each represent up to 
eight hexadecimal digits. If less than eight digits are 
specified, the string is right justified in a fullword and 
left— filled with zeros. If two or more hexwords are specified, 
they must be separated by one or more blanks. 

Xreg hexwordl [hexword2. .. ] 

stores the hexadecimal data (hexwordl [ hexword2. . . ]) in 
successive control registers starting at the register 
specified by reg. The reg operand must either be a decimal 
number from 0-15 or a hexadecimal digit from 0— F. If the 
virtual machine is in basic control mode, you can store data 
in register only. 

The operands (hexwordl [ hexword2. . . ]) each represent up to 
eight hexadecimal digits. If less than eight digits are 
specified, the string is right justified in a fullword and 
left— filled with zeros. If two or more hexwords are specified, 
they must be separated by one or more blanks. 

PSW [hexwordl] hexword2 

stores the hexadecimal data ([hexwordl] hexword2) in the first 
and second words of the virtual machine's program status word 
(PSN). If only hexword2 is specified, it is stored into the 
second word of the PSW. The operands hexwordl and hexword2 
must be separated by one or more blanks. They represent up to 
eight hexadecimal digits. If less than eight digits are 
specified, the string is right justified and left— filled with 
zeros. 
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STATUS stores selected virtual Machine data in certain low storage 
locations of the virtual Machine, simulating the hardware 
store status facility. These locations are permanently 
assigned locations in real storage. To use the STATUS 
operand, your virtual Machine Must be in the Extended Control 
Bode. The STATUS operand should not be issued for CHS virtual 
Machines or for DOS virtual Machines generated for a CPU 
SMaller than a SysteM/360 Model 40. The STATUS operand stores 
the following data in low storage: 

DeciMal Hexadecimal Length 

llllIlsSss Address in Bytes D at a 

216 ~ D8~ 8 CPU TiMer 

224 E0 8 Clock CoMparator 

256 100 8 Current PSW 

352 160 32 Floating-point registers 0-6 

384 180 64 General registers 0-15 

448 1C0 64 Control registers 0-15 



Res£onse 
STORE COMPLETE 
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Use the SYSTEM conmand to simulate the action of the RESET and RESTART 
buttons on the real computer console, and to clear storage. The RESET 
function and the CLEAR function leave the virtual machine in a stopped 
state. An IPL command must be issued after a SYSTEM CLEAR command. 
After a SYSTEM RESTART, the virtual machine is automatically restarted 
at the location loaded into the PSW from the doublevord at virtual 
location zero. The format of the SYSTEM command is: 



i— 






■ 


1 

1 
1 


SYStem | 
1 
1 


(CLEAR ) 
PRESET > 

(restart) 


1 
1 
1 


L_ 






_ _ j 



where: 
CLEAR 

RESET 

RESTART 



clears virtual storage and virtual storage keys to binary 
zeros. 

clears all pending interrupts and conditions in the virtual 
machine. 

simulates the hardware system RESTART function by storing the 
current PSW at virtual location eight and loading, as the new 
PSW, the doubleword from virtual location zero. Interrupt 
conditions and storage remain unaffected. 



Responses 

STORAGE CLEARED - SYSTEM RESET 

This response is given if the command SYSTEM CLEAR is entered. 

SYSTEM RESET 

This response is given if the command SYSTEM RESET is entered. 

If the command SYSTEM RESTART is entered, no response is given; the 
virtual machine resumes execution at the address in the virtual PSW 
loaded from virtual storage location zero. 
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Use the TAG command to associate information vith a VH/370 spool file, 
usually for use vith a subsystem such as RSCS or a user-written 
subsystem. The format of the TAG command is: 




Printer 
PUnch 
DBV S CONsole ( [text] 
vaddr 

FILE spoolid [text] 

( Printer 
J POnch 
DEV \ CONsole 
QUERY I (vaddr 

FILE spoolid 



wher e : 

DEV / PRINTER \ [text] 

PRT 

PUNCH 

PCH 

CONSOLE 

vaddr 

associates information (via the text operand described further 
on) with your virtual printer, punch, or console, or with the 
device specified by vaddr. 

FILE spoolid [text] 

replaces information previously associated vith the file via 
the text operand with the current text (described further on) . 
This operand can be specified only for reader spool files 
gueued on your virtual machine. 

The spoolid operand is the spool file identification, a number 
between 1 and 9900 assigned by CP when the spool file was 
closed. 

text defines a field (up to 136 characters long) that can contain 
any information you desire. Typically, this field contains 
meaningful parameters you want to associate with a spool file. 
The field of data specified in the TAG text operand is made 
available to virtual machines using the spool file, but is in 
no way modified or interpreted by VH/370. 

Certain control and addressing information meaningful to RSCS 
can be specified in this field. For details on how to use the 
TAG text operand to transmit files across the RSCS network, 
refer to the following section, tUsing the TAG Text Operand to 
Transmit Files to Remote Locations. n 
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PRINTER 

PRT 
DEV ] PUNCH 

PCH 
l j j CONSOLE 
| QUERY / I vaddr 

I 1 FILE spoolid 

| displays at your terminal the current setting of the TAG text 

! associated with a given spool file or virtual device. The 

| operands used with the TAG QUERY command correspond to the 

I operands used with TAG itself. For example, you create a text 

| setting by issuing the command: 

| TAG DEV PUNCH text 

| To find out the setting of that text field, issue the command: 

| TAG QUERY DEV PUNCH 

| If you know the spoolid of a file gueued to your virtual 

I machine reader and you wish to know the text setting for that 

| file, use the command: 

| TAG QUERY FILE spoolid 

| Spool identification (spoolid) numbers can be obtained using 

| the CP QUERY command with the READER, PRINTER or PUNCH 

I operand. 



I Dsinq the TAG Text Operand to Transmit Files to Remote Locations 

| The RSCS control program interprets the TAG text operand as addressing 

| and control parameters. If you are spooling a file to the RSCS virtual 

| machine to be transmitted to a remote station, code the TAG text operand 

| as follows: 

| locid [userid] [priority] 

I where: 

| locid is the location identifier (one to eight alphameric digits) of 

i the location to which the file is being transmitted. Your 

j system programmer can give you the locids of remote stations 

| attached to your virtual machine. 

| userid is the userid of the VH/370 virtual machine (a one- to 

j eight— character user identification) to which a file is being 

j transmitted. This operand is used by remote stations when they 

j transmit files to the RSCS virtual machine and want the files 

j sent to a particular VH/370 virtual machine. You can ignore 

| this operand if you are not specifying a priority. However, if 

j you are specifying a priority, you must code a userid operand, 

I even though it is ignored by RSCS. 

| priority is the reguested transmission priority, a decimal number 

| between and 99. The highest transmission priority is 0, next 

| highest is 1 , and so on. If you wish to specify this operand, 

| you must also specify a userid operand. 
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I Altering Spool File TAG Information 



| When a spool file you created is closed, it is enqueued on a virtual 
| machine reader of the virtual machine you specified in the SPOOL 
| command. You cannot change the TAG information associated with that 
I file unless the operator of the virtual machine to which the file was 
| spooled (the RSCS operator) transfers the file back to your virtual 
| machine. 

| To change the TAG information associated with a file in your virtual 
j reader, you can issue the TAG command with the spoolid operand 
| specified: 



I 



TAG FILE spoolid new text information 



| This command causes previous TAG text 
j replaced by the new text specified. 



information to be completely 



| When you enter the command with no new text specified: 

| TAG FILE spoolid 

| the text field associated with the file is set to all blanks. 
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TERMINAL 



Privilege Class: G 



Use the TERMINAL command to control the 
with your virtual console: 



following functions associated 



• Logical line-editing symbols 

• Basking of password 

• The APL character set 

• Signalling of an attention interrupt 

• Attention handling mode for your virtual console 

• Line length for output on your virtual console 

The terminal settings you specify with the TERMINAL command are in 
effect for only the duration of that terminal session. Ihenever you log 
on, the system defaults are in effect. However, the settings you 
specify for line-editing and MODE are still in effect when you log on 
after disconnecting. All the other operands (MASK, APL, ATTN, and 
LINE SIZE) are reset if you log on after disconnecting. 

Although you can define line-editing symbols and status with the 
TERMINAL command, the LINEDIT operand of the SET command determines 
whether the VM/370 line-editing functions are on or off. 

If an error occurs during processing of the command, all functions 
preceding the one with the error are in effect. The format of the 
TERMINAL command is: 



TERHinal 



CHardel 
LINEDel 
LIHEHd 
Escape 

Mask 

APL 

ATtn 

MODE 




{oFf} 

{s } 



LINESize nnn 



1 More than one function can be specified in a single entry of the 
TERHINAL command. For example: 



TERHINAL CHARDEL OFF HASK ON LINESIZE 90 



where: 



CHARDEL 




defines the logical character delete symbol. If ON is 
is specified, the default symbol becomes the logical 
character delete symbol. The default symbol is normally 
a, but depends on what is specified in your VH/370 
directory entry. If OFF is specified, no logical 
character delete symbol is allowed. If char is specified, 
that character (which must be a special character) 
becomes the logical character delete symbol. Unless 
otherwise specified, CHARDEL ON is in effect. 
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LINEDEL (ON \ defines the logical line delete symbol. If ON is 
OFF > specified, the default symbol becomes the logical line 
char ) delete symbol. The default symbol is normally t, but 
depends on what is specified in your VM/370 directory 
entry. If OFF is specified, no logical line delete 
symbol is allowed. If char is specified, that character 
(which must be a special character) becomes the logical 
line delete symbol. Unless otherwise specified, LINEDEL 
ON is in effect. 

LINEND (ON \ defines the logical line end symbol. If ON is 
OFF > specified, the default symbol becomes the logical line 
char) end symbol. The default symbol is normally #, but 
depends on what is specified in your VM/370 directory 
entry. If OFF is specified, no logical line end symbol 
is allowed. If char is specified, that character (which 
must be a special character) becomes the logical line end 
character. Unless otherwise specified, LINEND ON is in 
effect. 

ESCAPE (ON \ defines the logical escape character. If ON is specified, 
OFF > the default symbol becomes the logical escape character, 
char ) The default symbol is normally " , but depends on what is 
specified in your VM/370 directory entry. If OFF is 
specified, no logical escape character is allowed. If 
char is specified, that character (which must be a 
special character) becomes the logical escape character. 
Unless otherwise specified, ESCAPE ON is in effect. 



TON \ 
(OFF J 



MASK | ON ^ controls the typing of a mask line at a typewriter 
terminal that is not equipped with the Print Inhibit 
feature, when a password is to be entered. If MASK ON is 
specified, VM/370 types the mask line. If MASK OFF is 
specified, the mask line is not typed and it is up to 
each user to preserve the security of his password. The 
MASK operand does not apply to the IBM 3215 or to similar 
system console or display terminals that do not have a 
Print Inhibit feature. Unless otherwise specified, MASK 
OFF is in effect. 

APL ( ON ) controls the use of APL character translation tables. 
\0FFJ If APL ON is specified, CP uses the translation tables 
for terminals equipped with the standard APL typing 
element. If APL OFF is specified, CP uses the normal 
translation tables (that is, BCD or correspondence 
code) . If APL ON is specified, the LINESIZE value is 
overridden. Unless otherwise specified, APL OFF is in 
effect. 

This operand cannot be changed for a 3704/3705 device in 
NCP mode. If however, the terminal is connected to a 
2701/2702/2703 line control unit, the operand is valid. 
3704/3705 users cannot use this option in NCP mode. 

The APL operand is not valid for display type terminals. 

Note: APL ON also applies to the 3767 terminal equipped 
with the APL alternate character selection. 



332 IBM VM/370: Command Language Guide for General Users 



GC20-1804-3 Page Modified by TNL GN20-2659 

TERMINAL 



ATTN (ON ) controls signalling of an attention interrupt. If ATTN 

{ GFFj ON is specified, the exclamation point is displayed when 
an an attention interrupt occurs. The OFF option 
suppresses the displaying of the exclamation point (!) 
and carrier return for those systems that perform special 
line editing using the Attention key. Unless otherwise 
specified, ATTN ON is in effect. 

The ATTN operand is not valid for display type 
terminals. 



MODE 






controls the terminal attention envi 
that one or more attentions force 
into the CP environment. VM specifi 
is reflected to your virtual machin 
one attention forces your virtual 
environment. VM is the default f 
except the primary system operator, 
see "Interrupting the Execution of 
2. 



ronment. CP speciries 
the virtual machine 
es that one attention 
e and that more than 
machine into the CP 
or all VM/370 users 
For more information 
a Command" in Section 



| LINESIZE nnn 



specifies the maximum allowable line length for terminal 
output, nnn can be a number from 1 through 255. 

Note: If APL ON is specified, CP does not separate output 
lines into LINESIZE segments. Instead, an output length 
of 1760 is allowed and CP assumes that the APL system has 
inserted the appropriate carriage control characters. 



Responses 



None. 



Section 8: Format and Usage Rules for CP Commands 333 



TRACE 



TRACE 



Privilege Class: G 



Dse the TRACE command to trace specified virtual Machine activity and to 
record the results at the terminal, on a virtual spooled printer, or on 
both terminal and printer. If trace output is being recorded at the 
terminal, the virtual machine stops execution and CP command mode is 
entered after each output message. This simulates the single cycle 
function. To resume operation at the virtual machine, the BEGIN command 
must be entered. If the RON operand is specified, the virtual machine is 
not stopped after each output message. If trace output is being 
virtual spooled printer, a CLOSE command must be issued to 
in order for the trace output to be printed. Successful 
the next sequential instruction and branch-to-self 
are not detected by TRACE. Instructions that modify or 
first two bytes of the next sequential instruction cause 



recorded on a 
that printer 
branches to 
instructions 
examine the 



erroneous processing for BRANCH and INSTRUCT tracing. 



fihen tracing on a virtual machine with only one printer, the trace 
data is intermixed with other data sent to the virtual printer. To 
separate trace information from other data, define another printer with 
a lower virtual address than the previously defined printer. For 
example, on a system with 00E defined as the only printer, define a 
second printer as 00B. The regular output goes to 00E and the trace 
output goes to 00B. 

When operation of a shared system is being traced, the following 
options cannot be used: 

• BRANCH 

• INSTRUCT 

• ALL 



I/O operations for virtual channel-to-channel adapters, with 
connected to the same virtual machine, cannot be traced. 



both ends 



The format of the TRACE command is: 



TRace 



SVC v 1 


Printer 






I/O \ 


r t 


r t 




PROgram I 


ITERMinalj 


|NORun| 




EXTernal / 


IBOTH | 


|RUN | 




PRIV 


L J 


L J 




SIO ) 








CCM ( 


OFf 






BRanch V 


L 




J 


INSTruct 1 








ALL J 








csw / 









END 



'More than one of these activities may be traced by using a single 
TRACE command. For example: 



TRACE SVC PROGRAM SIO PRINTER 
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TRACE 

w b ere : 

SVC traces virtual machine SVC interrupts. 

I/O traces virtual machine I/O interrupts. 

PROGRAM traces virtual machine program interrupts. 

EXTERNAL traces virtual machine external interrupts. 

PRIV traces all virtual machine non-I/O privileged instructions. 

| SIO traces TIO, CLRIO, HIO, HDV and TCH instructions to all 
j virtual devices. Will also trace SIO and SIOF instructions 

I for non-console and non-spool devices only. 

CCW traces virtual and real CCWs for non-spool/non-Console device 
I/O operations. When CCW tracing is requested, SIO and TIO 
instructions are also traced. 

BRANCH traces all virtual machine interrupts, all PSW instructions, 
and all successful branches. 

INSTRUCT traces all instructions, virtual machine interrupts and 
successful branches. 

ALL traces all instructions, interrupts, successful branches, 
privilege instructions, and virtual machine I/O operations. 

CSW provides contents of virtual and real channel status words at 
I/O interrupt. 

END terminates all tracing activity and prints a termination 
message. 

PRINTER directs tracing output to a virtual spooled printer. 
PRT 

TERMINAL directs tracing output to the terminal (virtual machine 
console) . 

BOTH directs tracing output to both a virtual spooled printer and 
the terminal. 

OFF halts tracing of the specified activities on both the printer 
and terminal. 

UP-BUl! stops program execution after the trace output to the terminal 
and enters CP command mode. 

| JBote: If a Diagnose code X'008' is being traced, NORDN has no 

| effect and program execution does not stop. 

RUN continues the program execution after the trace output to the 
terminal has completed and does not enter CP command mode. 

Notes: 

1. If your virtual machine has the virtual=real option and NOTRANS set 
on, CP forces CCW translation while tracing either SIO or CCW. When 
tracing is terminated with the TRACE END command, CCW translation 
is bypassed again. 

2. If the virtual machine assist feature is enabled on your virtual 
machine, CP turns it off while tracing SVC and program interrupts 
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(SVC, PBIV, BRANCH, INSTRUCT, or ALL). After the tracing is 
terminated with the TRACE END command line, CP turns the assist 
feature on again. 



Responses 



The following symbols are used in the responses received from TRACE: 



Symbol 
vvvvvv 
tttttt 
rrrrrr 
xxxxxxxx 

yyyyyyyy 

ss 
ns 
zz 

zzzzzzzz 
type 

V vadd 
R radd 
mnem 
int 
code 
CC n 
IDAL 
*** 

==> 



Meaning 

virtual storage address 

virtual transfer address or new PSW address 

real storage address 

virtual instruction, channel command word, CSW status 

real instruction, CCW 

argument byte (SSM-byte) for SSM instruction 

new system mask after execution of STOSM/STNSM 

low order byte of R1 register in an execute instruction 

(not shown if R1 register is register 0) 
referenced data 
virtual device name (DASD, TAPE, LINE, CONS, RDR, 

PRT, PON, GRAF, DEV) 
virtual device address 
real device address 
mnemonic for instruction 
interrupt type (SVC, PROG, EXT, I/O) 
interrupt code number (in hexadecimal) 
condition-code number (0, 1, 2, or 3) 
Indirect data address list 
virtual machine interrupt 
privileged operations 
transfer of control 



TRACE STARTED 

This response is issued when tracing is initiated. 

TRACE ENDED 

This response is issued when tracing is suspended. 

I TCH, TIO, CLRIO, HIO, HDV, SIO, or SIOF 

TCH 

I/O vvvvvv TCH xxxxxxxx type vadd CC n 

HO, CLRIO, HIO, or HDV 

I/O vvvvvv mnem xxxxxxxx type vadd CC n type radd CSW xxxx 

SIO or SIOF 

I/O vvvvvv mnem xxxxxxxx type vadd CC n type radd CSW xxxx CAW vvvvvvvv 

CCW: 

ccw vvvvvv xxxxxxxx xxxxxxxx rrrrrr yyyyyyyy yyyyyyyy 
CCW IDAL vvvvvvvv vvvvvvvv IDAL OOrrrrrr OOrrrrrr 
ccw seek xxxxxxxx xxxxxx seek yyyyyyyy yyyy 
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TRACE 

The IDAL or SEEK line is included only if applicable. The virtual IDAL 
is not printed if the real CCR opcode does not natch the real CCW. 

INSTRUCTION TRACING: 

Privileged Instruction: 

: www SSH xzxxxxxz ss (noraal SSH) 

: www SSH xxxxxxxx ss tttttt (switch to/froa translate aode) 

: www STOSH xxxxxxxx ns (noraal STOSH) 

: www STOSH xxxxxxxx ns tttttt (switch to translate lode) 

: www STNSH xxxxxxxx ns (norial STNSH) 

: www STHSH xxxxxxxx ns tttttt (switch froi translate aode) 

: www LPSW xxxxxxxx tttttttt tttttttt (IAIT bit on) 

: www LPSW xxxxxxxx ==> tttttttt tttttttt (WAIT bit not on) 

: www anea xxxxxxxx (all others) 

Executed Instructions: 

www EX xxxxxxxx zz www anea xxxx xxxxxxxx 

For an executed instruction, where zz (see preceding explanation of 
syabols) is nonzero, the aneaonic for the executed instruction is given 
as if the zz byte had been put into the instruction with an OR 
operation. 

All Other Instructions: 
www anea xxxxxxxx xxxx 



SUCCESSFUL BRANCH: 

www anea xxxxxxxx ==> tttttt 

INTBRRUPT (SVC, PROGRAM, or EXTERNAL) 
*** www int code ==> tttttt 

I/O INTERRUPT (First line given only if «CSW« was specified) 

csw v vadd xxxxxxxx xxxxxxxx r radd yyyyyyyy yyyyyyyy 
*** www I/O vadd ==> tttttt CSW xxxx 

BRANCH TRACE: (ALL option selected) 
Entry for 'branch froa' instruction 
www anea xxxxxxxx tttttt 
Entry for 'branch to' instruction 
==> www anea xxxxxxxxxxxx 
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TRANSFER 



TRANSFER 



EEiiii^Sie Class: G 



Use the TRANSFER command to direct your input file to a specified reader 
or to reclaim virtual reader files that you spooled to another user. 
The TRANSFER command does not transfer any active spool files. The 
format of the TRANSFER command is: 



TRANs fer 



spoolid j 
Class c ( 
ALL ) 



| To userid 



I 



Ir il 

I | From ( userid) 1 1 
II Ull /ii 



J l 

j 



where: 



spoolid 



CLASS c 



is the input file to be directed to or retrieved from 
the named userid. 

transfers all input files of the specified class (c) . 
The c is a one— character alphameric field with values 
from A to Z and from to 9. 



[TO] userid 



ALL transfers all input spool files. 

is the user to whom the files are to be directed. If 
the optional keyword TO is omitted, the userid may not 
be TO or T. The file is deleted from your reader if you 
use this option. 

[FROM] (userid) is the user from whom input spool files are to be 
(ALL j reclaimed. ALL may be specified to reclaim input spool 
files that were originated by your virtual machine from 
all users. 



Responses 

RDR FILE spoolid TRANSFERRED J TO \ 

(FROM J 



userid 



where: 
spoolid 

TO userid 

FROM userid 



is the spool file identification number of the file 
that is spooled. The number does not change. 

is the response to the user who currently owns the 
file and userid is the recipient of the file. 

is the response to the user who receives the 
transferred file and userid is the sender. 



( nnnn) 



FILES TRANSFERRED 



This is the response you receive when you issue the TRANSFER 
command. It is not displayed if you issued the CP SET IHSG OFF 
command line. 
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Appendix A: Functions of VM/370 Commands 



Figures 36 through 44 present a functional summary of commands available 



j 

j Function 


I 
Command 


| Begin terminal session (identify 


| LOGON 


| user to VM/370 system) . 




| End terminal session. 


LOGOFF 


| Communicate with other VM/370 users 


MESSAGE 


| and with the system operator. 




| Connect a terminal to a multi-access 


DIAL 


| virtual machine. 




| Disconnect a user's terminal from a 


DISCONN 


| virtual machine. 




| Test terminal hardware. 


ECHO 


| Start or stop console spooling. 


SPOOL 


| Control terminal input and output. 




| • Indicate if accounting data is to be 


SET 


| received at the terminal. 




| • Indicate if messages from other users 


SET 


| are to be received at the terminal. 


SET 


| • Control output of certain informational 


SET 


| responses. 




| • Control line editing functions. 


SET 


| • Control format of messages received at 


SET 


| the terminal. 


SET 


| • Set up program function key cataloged 


SET 


| procedures. 




| • Print the current screen display on the 


SET 


| printer (remote display units only) . 




| • Get information about terminal control 


QUERY 


| parameters. 


QUERY 




QUERY 


| • Set attention handling mode. 


TERMINAL 


| • Specify method of password entry. 


TERMINAL 


| • Specify use of additional translation 


TERMINAL 


| tables. 




| • Specify terminal line size. 


TERMINAL 


| • Specify ATTN key handling procedures. 


TERMINAL 


| • Specify that ATTN key will not stop the 


SET 


| virtual machine. 




| • Specify characters to indicate CPU 


SET 


I time interval reporting. 




I • Specify format of CMS READY message. 


SET 


| • Indicate character translations to be 


SET 


I done during terminal input and output. 


SET 



! Subcommand 

or 

Option 



CONSOLE 



ACNT 

MSG 
HNG 
IMSG 

LINEDIT 
REDTYPE 
EMSG 
PFnn 

PFnn COPY 

TERMINAL 

PFnn 

REDTYPE 

MODE 

MASK 

APL 

LINE SIZE 

ATTN 

RUN 

BLIP 

RDYMSG 

INPUT 

OUTPUT 



CP 
CP 

CP 

CP 

CP 
CP 

CP 

CP 
CP 
CP 

CP 
CMS 
CP 
CP 

CP 

CP 

CP 

CP 

CMS 

CP 

CP 

CP 

CP 
CP 
CP 

CMS 

CMS 
CMS 
CMS 




Figure 36. Commands to Control a Terminal Session 
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Function 



Change attributes of a spooled file. 

Create a source program file from the 
terminal. 

Invoke the System Assembler to assemble 
a source program. 

Invoke the VS BASIC Compiler. 

Invoke the PL/I optimizing Compiler. 

Invoke the PL/I Checkout Compiler. 

Invoke the PL/I Checkout Compiler and 
Execute a Program. 

Invoke the FORTRAN Code and Go Compiler. 

Invoke the FORTRAN G Compiler. 

Invoke the FORTRAN H Complier. 

Create or list macro libraries to be used 
during assemblies or compilations. 

Create or list subroutine libraries. 

Specify macro libraries to be searched 
during assemblies or compilations. 

Specify subroutine libraries to be 
searched during LOAD and INCLUDE 
function. 

Bring object code into main storage. 

Create a MODULE (core-image) file. 

Bring MODULE files into storage. 

Print a storage map of a MODULE file. 

Build auxiliary module directories. 

Begin execution of programs which were 
previously loaded into main storage. 




ASSEMBLE 

VSBASIC 
PLIOPT 
PLIC 
PLICR 

TESTFORT 
FORTGI 
FORTHX 
MACLIB 

TXTLIB 
GLOBAL 

GLOBAL 

LOAD 
INCLUDE 

GENMOD 

LOADMOD 

MODMAP 

GENDIRT 

START 



Subcommand 

or 

Option 



MACLIB 



TXTLIB 




CMS 

CMS 
CMS 
CMS 
CMS 

CMS 
CMS 
CMS 
CMS 

CMS 
CMS 

CMS 

CMS 
CMS 

CMS 

CMS 

CMS 

CMS 

CMS 



Figure 37. Commands to Develop Programs and Process Data (Part 1 of 2) 
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Function 



Simulate OS Data Definition (DD) JCL 
cards during program execution. 

List information about OS data sets or 
DOS files. 

1 n^A •* rx A /■> v « " « * »» ^U-4^^.4- fmovnil -C-JT^^ 

Compile, load, and execute source files. 

Load and execute core-image (MODULE) 
files. 



Command 
FILEDEF 

LISTDS 

n riu 
nun 

RON 
RUN 



Subcommand 

or 

Option 



Type 
CMS 

CMS 

f uc 

v~ no 

CMS 
CMS 



Figure 37. Commands to Develop Programs and Process Data (Part 2 of 2) 



Function 

Stop execution at a specified virtual 
machine location. 

Resume execution of a stopped 
virtual machine. 

Display virtual storage, registers, 
PSD, and so on. 



Print the contents of virtual storage 
locations on the spooled printer. 

Change the contents of registers and 
storage locations. 



Trace virtual machine SVC calls. 

Trace virtual machine instructions, I/O 
operations, SVC calls, and so on. 

Convert system ABEND dumps to printed 
output. 

Trace events that occur on the real 
machine. 





Subcommand 






or 




| Command 


Option 


Type | 


| ADSTOP 




CP | 


| DEBUG 


BREAK 


CMS | 


| BEGIN 




CP | 


| DEBUG 


GO 


CMS | 


| DISPLAY 




CP | 


| DEBUG 


GPR 


CMS | 


| DEBUG 


PSW 


CMS | 


| DEBUG 


X 


CMS | 


| DUMP 




CMS | 


| DEBUG 


DUMP 


CMS | 


| STORE 




CP | 


| DEBUG 


STORE 


CMS | 


| DEBUG 


SET 


CMS | 


| SVCTRACE 




CMS | 


| TRACE 




CP | 


| VMFDUMP 




CMS | 


| MONITOR 


START 
CP TRACE | 


CP | 


| MONITOR 


STOP 
CP TRACE 


CP | 



Figure 38. Commands to Test and Debug a Program 
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Function 



Create a file from teriinal input. 
Create a file from card input. 

Verify the existence of a file on disk. 
Erase a file (or files) from disk. 



List names of files on disk and their 
attributes. 

Display the contents of a file at the 
terminal. 

Print the contents of a file or a member 
of a library on a spooled printer. 

Punch the contents of a disk file on a 
spooled punch. 

Sort the records of a file into ascending 
order based on specified sort fields. 

Copy one disk file to another disk file. 



Combine several files into one file. 

Copy data from one device type to 
another device type . 

Change the name of a CMS file. 

Compress a file by encoding multiple 
contiguous occurrences of a single 
character. 

Rearrange the contents of records in a 
disk file. 

Perform character translations on 
specified characters in a disk file. 

Append one file to the end of another 
file. 

Remove trailing blanks from records in a 
file. 

Compare the contents of two disk files. 

Change records in a file based on 
record seguence numbers. 




READCARD 
DISK 

STATE 

ERASE 
ACCESS 

LISTFILE 



TYPE 

PRINT 

PUNCH 
DISK 

SORT 

MOVEFILE 
COPYFILE 

COPYFILE 

MOVEFILE 

RENAME 
COPYFILE 

COPYFILE 

COPYFILE 

COPYFILE 

COPYFILE 

COMPARE 
UPDATE 



Subcommand 

or 

Option 



LOAD 



ERASE 



DUMP 



PACK 



TRANS 



APPEND 



TRUNC 



Type 

CMS 

CMS 
CMS 

CMS 

CMS 

CMS 

CMS 
CMS 
CMS 



CMS 
CMS 

CMS 



CMS 
CMS 

CMS 

CMS 

CMS 
CMS 

CMS 

CMS 

CMS 

CMS 

CMS 
CMS 



Figure 39. Commands to Update Data Files (Part 1 of 2) 
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Function 


| Command 


I Subcommand 

or 
| Option 


— — i 

i Type j 


Terminate spooling operations on a 
virtual unit record device or console. 


| CLOSE 




1 CP j 


Load the virtual forms control buffer 
(FCB) . 


LOADVFCB 




CP | 


Indicate order of processing for spooled 
files. 


i ORDER 




cp j 


Remove spooled files from the system. 


PURGE 




CP | 


print documents according to the control 
words in the document file. 


SCRIPT 




CHS { 


Change options in effect for spooling 
operations. j 


SPOOL 




CP | 


Spool input files to or from another 
user. 


TRANSFER 




CP | 


Copy data from tape to disk. 


TAPE 


LOAD 


CHS ( 


Copy data from disk to tape. 


TAPE 


DUMP 


CHS | 


Convert OS partitioned data set (PDS) 
files or card-image files on tape to | 
format on disk. 


TAPPDS 




CHS | 



Figure 39. Commands to Update Data Files (Part 2 of 2) 



1 

j Function 


! 

i Command 


| Logically connect a disk to a virtual 
I machine. 


I LINK 


| Logically disconnect a device from a 
j virtual machine. 


DETACH 


I Hake files on a disk available to a user. 


ACCESS 


j Remove accessibility to files. 


RELEASE 


j Dump a disk to tape. 


DDR 


j Restore a disk from tape. 


DDR 


j Format disk space in CHS format. 


FORHAT 



I Subcommand ! 

or 

Option 




Figure 40. Commands to Control Disks 
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Function 



Load a virtual machine operating system. 

Alter the virtual Machine configuration. 

Disconnect the user's terminal from the 
VH/370 system. 

Enter control program commands from a 
CHS virtual machine. 

Communicate with other virtual machine 
users or with the system operator. 

Simulate an external interrupt for a 
virtual machine. 

Simulate 'not ready* for a virtual 
device. 

Simulate functions of buttons on the 
real CPU console. 

Place virtual machine console in dormant 
state with keyboard locked. 

Perform tape rewind action. 

Establish VH/370 directory entries. 

Simulate device end interrupt to a 
virtual machine device. 

Simulate console interrupt. 



Beset pending interrupts for virtual 
devices. 

Invoke table of synonyms for CHS command 
names. 

Set the functions controlling forms for 
command operand, options, names. 



Command 



IPL 

DEFINE 

DISCONN 

CP 

HSG 

EXTERNAL 

NOTBEADT 

SYSTEH 

SLEEP 

REMIND 
TAPE 

DIRECT 

BEADT 



ATTN 
BEQUEST 

BESET 



SYNONTH 



SET 



Subcommand 

or 

Option 



BEN 



ABBBEV 

IHPEX 

IHPCP 



Type 
CP 
CP 
CP 

CHS 

CP 

CP 

CP 

CP 

CP 

CP 
CHS 

CHS 

CP 



CP 
CP 

CP 



CHS 



CHS 
CHS 
CHS 



Figure 41. Commands for Virtual Hachine Control (Part 1 of 2) 
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Function 



Indicate if I/O is to be done as 
specified by the virtual machine with no 



Control timer updating. I SET I TIMER 

Change or set the number of loader } SET | LDBTBLS 
tables for a CMS virtual machine. 

Indicate if pages of storage are to be I SET I RELPAGE 
released after the execution of certain 
CMS commands. 

Get information about virtual machine | QUERY 
status. 

Set Virtual Machine Assist feature I SET 
on or off. 

Set the pseudo page fault portion of I SET 
VM/VS Handshaking feature on or off. 
i 

Figure 41 . Commands for Virtual Machine Control (Part 2 of 2) 



Command 
SET 

SET 



Subcommand 

or 

Option 

NOTRANS 



ASSIST 



PAGEX 



Type 



CP 



CP 



CMS 



CP 



CP 



CP 
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r - 




Subcommand 
or 




| Function 


Command 


Option 


Type 


| Create accounting records for logged on 


ACNT 




CP 


| users and reset accounting data. 








| Logically connect or dedicate devices 


ATTACH 




CP 


| to a virtual machine or to CP. 








| Logically disconnect devices from 


DETACH 




CP 


| a virtual machine or from CP. 








| Disable communication lines. 


DISABLE 




CP 


| Enable communication lines. 


ENABLE 




CP 


| Force a specific user to log off CP. 


FORCE 




CP 


| Terminate active channel CP program on a 


HALT 




CP 


| specific device. 








| Control paging activity. 


LOCK 




CP 




UNLOCK 




CP 


| Request information about real and 


QUERY 




CP 


| virtual machine characteristics. 








| Establish system parameters. 


SET 




CP 


| Terminate functions and checkpoint 


SHUTDOWN 




CP 


| system. 








| Transmit high priority messages to users. 


WARNING 




CP 


| Control 3704/3705 control program 


NETWORK 


LOAD 


CP 


| functions. 




DUMP 

ENABLE 

DISABLE 

TRACE 

HALT 

SHUTDOWN 

POLLDLAY 

QUERY 

VARY 

DISPLAY 





Figure 42. Commands to Control VM/370 
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Function 

Restart or reposition the current output 
of an output spooling device. 

Change attributes of a closed spool file 

Terminate spooling activity on a virtual 
spooled unit record device or console. 

Halt operations of specified spooling 
devices following completion of current 
activity. 

Cancel current output on a real unit 
record device. 

Cancel spool HOLD status. 

Defer spooled output of a particular 
user. 

Load printer UCS or FCB buffer. 

Cause spooled files to be processed in a 
specific order. 

Remove closed spool files from the 
system . 

Reguest information about spool files. 

Repeat printing or punching of current 
file on a specific output device. 

Force a printer to single space output. 

Modify spooling options for reader, 
printer, punch, and console spool files. 
Initiates and terminates virtual console 
spooling. 

Start spooling device after draining or 
changing output class. 

Spool files to or from a user's card 
reader. 

Direct a file to a remote location. 



Assign attributes and/or characteristics 
to a spool file. 

Reguest display of the attributes and 
characteristics associated with a spool 
file. 



Command 
BACKSPAC 

CHANGE 
CLOSE 

DRAIN 

FLUSH 

FREE 
HOLD 

LOADBUF 
ORDER 

PURGE 

QUERY 
REPEAT 

SPACE 
SPOOL 

START 
TRANSFER 



SPOOL 
TAG 

TAG 
SPOOL 



TAG 



Subcommand 

or 

Option 




CP 
CP 

CP 

CP 

CP 
CP 

CP 
CP 

CP 

CP 
CP 

CP 
CP 

CP 
CP 



CP 
CP 

CP 
CP 

CP 



Figure 43. Commands for Spooling Control 
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Function 



Display real storage at terminal. 

Dump real storage to virtual spooled 
printer. 

Display conditions that may affect systei 
loading. 



Find locations of control blocks. 

Record samples of system data for 
performance analysis. 



Save virtual machine storage space 
on disk . 

Perform intensive recording of device 
activity information. 

Set the error recording mode for soft 
machine checks. 

Dump error information which has been 
recorded by error recording routines. 



Command 


Subcommand 

or 

Option 


DCP 




DHCP 




INDICATE 


LOAD 

USER 

QUEUES 

I/O 

PAGING 


LOCATE 




HONITOR 


DISPLAY 

ENABLE 

INTERVAL 

START 

STOP 


SAVESYS 




SET 


RECORD 



SET 



CPEREP 



MODE 



Type 
CP 
CP 

CP 



CP 
CP 



CP 



CP 



CP 



CMS 



Figure 44. Commands for System and Hardware Analysis 
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Appendix B: Debugging a Problem Program with VM/370 



How To Start Debugging 

Before you can correct any problem, you must recognize that one exists. 
Next, you must identify the problem, collect information and determine 

the cause SO + ha+" ■*■*»© DTQblom f»n Vio fWofl. Bhon rnnninn VM/^70- von 

must also decide whether the problem is in CP r the virtual machine, or 
the problem program. Once you determine that the problem is in CP or 
the virtual machine, refer to VM/370: System Programmer's Guide. 

A good approach to debugging is: 

1. Recognize that a problem exists. 

2. Identify the problem type and the area affected. 

3. Analyze the data you have available, collect more data if you need 
it, then isolate the data that pertains to your problem. 

4. Finally, determine the cause of the problem and correct it. 



DOES A PRO BLEU EXIST? 

There are four types of problems: 

1 . Loop 

2. Wait state 

3. ABEND (Abnormal End) 

4. Incorrect results 

The most obvious indication of a problem is the abnormal termination 
of a program. Whenever a program abnormally terminates, a message is 
issued. 

Another obvious indication of a problem is unexpected output. If your 
output is missing, incorrect, or in a different format than expected, 
some problem exists. 

Unproductive processing time is another symptom of a problem. This 
problem is not as easily recognized, especially in a time-sharing 
environment. 



IDENTIFYING THE PROBLEM 

Two types of problems are easily identified: abnormal termination is 
indicated by an error message, and unexpected results become apparent 
once the output is examined. The looping and vait state conditions are 
not as easily identified. 



Appendix B: Debugging a Problem Program with VM/370 351 



Ihen using YH/370, you are normally sitting at a terminal and do not 
have the lights of the CPU control panel to help you. You may have a 
looping condition if your program takes longer to execute than you 
anticipated. Also, check your output. If the number of output records or 
print lines is greater than expected, the output may really be the same 
information repeated many times. Repetitive output usually indicates a 
program loop. 

Another way to identify a loop is to periodically examine the current 
PSH. If the PSH instruction address always has the same value, or if the 
instruction address has a series of repeating values, the program 
probably is looping. 

The wait state is also difficult to recognize when at the terminal. 
Again, the console lights are unavailable. If your program is taking 
longer than expected to execute, the virtual machine may be in a wait 
state. Display the current PSH on the terminal. Periodically, issue the 
CP command 

QUERY TIME 

and compare the elapsed processing time. When the elapsed processing 
time does not increase, the wait state probably exists. 



ANALYZING TEE PROBLEM 

Once the type of problem is identified, the cause of it must be 
determined. There are recommended procedures to follow. These 
procedures are helpful, but they do not identify the cause of the 
problem in every case. Be resourceful. Use whatever data you have 
available. If the cause of the problem is not found after the 
recommended debugging procedures are followed, it may be necessary to 
undertake the tedious job of desk-checking. 

The section, "How To Use VM/370 Facilities To Debug," describes 
procedures to follow in determining the cause of various problems that 
can occur in the Control Program, in the virtual machine, or in the 
problem program. If you determine that there is a problem in CP or the 
virtual machine operating systei, refer to VM/370 ; System Programmer's 
Guide for debugging procedures. 



How To Use VM/370 Facilities To Debug 

Once the problem, and the area where it occurs, are identified, you can 
gather the information needed to determine the cause of the problem. The 
type of information you want to look at varies with the type of problem. 
The tools used to gather the information vary depending upon the area in 
which the problem occurs. For example, if the problem is looping, you 
will want to examine the PSH via the CP DISPLAY command. 

The following sections describe specific debugging procedures for the 
various error conditions. The procedures tell you what to do and what 
debug tool to use. For example, the procedure may say dump storage 
using the CP DUMP command. The procedure will not tell you how to use 
the debug tool. Refer to Sections 7 and 8 for a detailed description of 
each debug tool, including how to invoke it. 



352 IBM VM/370: Command Language Guide for General Users 



PROBLEM PROGRAM ABEND 

When an operating system or program does not know how to continue, it 
abnormally terminates. 

If a dump was taken, it was sent to the virtual printer. Issue a 
CLOSE command to the virtual printer to have the dump print on the real 
printer. 

If the problem can be reproduced, it may be helpful to trace the 
processing using the CP TRACE command. Also, you can set address stops, 
and display and alter registers, control words (such as the PSW) , and 
data areas. The CP commands can be very helpful in debugging because you 
can gather information at various stages in processing. A dump is static 
and represents the system at only one particular time. Debugging on a 
virtual machine can often be more flexible than debugging on a real 
machine. 

VM/370 may terminate or reset a virtual machine if a nonrecoverable 
channel check or machine check occurs in that virtual machine. Hardware 
errors usually cause this type of virtual machine termination. One of 
the following messages: 

DMKMCH616I MACHINE CHECK; USER userid TERMINATED 

DMKCCH604I CHANNEL ERROR; DEV XXX ; USER userid; MACHINE RESET 

appears on the CPU console. 

The address of the instruction causing the ABEND is found in the 
problem program area. 

Use the PSW and program listing to determine the cause of the ABEND. 
If the problem is not readily detected, use the CP debugging facilities 
to monitor the progress and status of the program as it executes. If 
the program is running under the control of CMS, you can use the CMS 
debug facilities as well. 



UNEXPECTED RESULTS IN A PROBLEM PROGRAM 

If a program has inaccurate, missing, or redundant output, a problem 
exists. Instead of taking dumps of storage and output and doing a lot 
of desk-checking, you can use the interactive facilities of the virtual 
machine environment to debug. Using the CP ADSTOP command, you can set 
an address stop, set the address stop at a strategic point in the 
processing, such as before a data transfer or computation, when 
execution stops, you can display or alter storage and set the next 
address stop. Also, consider using the CP TRACE command. You can often 
debug a problem program directly from the terminal. 

Both the CP and CHS commands can be used to debug programs under the 
control of CMS. 



PROBLEM PROGRAM DISABLED LOOP 

When a disabled loop in a problem program exists, you cannot communicate 
with the virtual machine's operating system. That means that signalling 
attention once does not cause an interrupt. 
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Enter CP node. 

1. Use the CP TRACE coaaand to trace the entire loop. Display general 
and extended control registers via the CP DISPLAY coaaand. 

2. lake a duap via the CP DUMP coaaand. 

3. IPL the virtual aachine again. 

Use the information just gathered, along with listings, to try to 
find the entry into the loop. 



PROBLEM PROGRAM ENABLED LOOP 

You should perform the following seguence when atteapting to find the 
cause of an enabled loop: 

1. Use the CP TRACE coaaand to trace the entire loop. CHS users can 
use the CP TRACE coaaand or the CMS SVCTRACE coaaand. Display the 
PSW and the general registers. 

2. Use the CP DUMP coamand to duap your virtual storage. CMS users 
can use the debug DUMP subconaand. A standalone duap aay be used, 
but be aware that such a duap destroys the contents of soae areas 
of storage. 

3. Consult the source code to search for the faulty instructions, 
exaaining previously executed subroutines if necessary. Begin by 
scanning for instructions that set the condition code or branch on 
it. 

4. If the aanner of loop entry is still undetermined, assuae that a 
wild branch has occurred and begin a search for its origin. 



PROBLEM PROGRAM DISABLED WAIT 

The VM/370 Control Prograa does not allow the virtual aachine to enter a 
disabled wait state or certain interrupt loops. Instead, CP notifies 
you of the condition with one of the following aessages: 

DMKDSP450W CP ENTERED; DISABLED WAIT PSW 

DMKDSP451W CP ENTERED; INVALID PSW 

DMKDSP452W CP ENTERED; EXTERNAL INTERRUPT LOOP 

DMKDSP453W CP ENTERED; PROGRAM INTERRUPT LOOP 

and enters the CP aode. Use the CP coaaands to display the following 
inforaation on the terainal. 

• PSW 

• CSW 

• General registers 

• Control registers 

Then use the CP DUMP coaaand to take a duap. 

If you cannot find the cause of the wait or loop froa the inforaation 
just gathered, try to reproduce the problem, this tiae tracing the 
processing via the CP TRACE coaaand. 
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If CHS is running in the virtual machine, the CHS debugging 
facilities may also be used to display information, take a dump, or 
trace the processing. The CHS SVCTRACE and the CP TRACE commands record 
different information. Figure 45 compares the two. 



PROBIEH PR06RAH ENABLED WAIT 

If the virtual machine is in an enabled wait state, try to find out why 
no I/O interrupt has occurred to allow processing to resume. 

The Control Program treats one case of an enabled wait in a virtual 
machine the same as a disabled wait. If the virtual machine does not 
have the "real timer" option and loads a PSW enabled only for external 
interrupts, CP issues the message 

DHKDSP450W CP ESTERED; DISABLED WAIT STATE 

Since the virtual timer is not decremented while the virtual machine 
is in a wait state, it cannot cause the external interrupt. A "real 
timer" runs in both the problem state and wait state and can cause an 
external interrupt which allows processing to resume. 
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Comparison of CP and CMS Facilities for Debugging 

If you are debugging problems while running CMS, you can choose the CP or CMS debugging 
tools. Refer to Figure 45 for a comparison of the CP and CMS debugging tools. 



1 

Function | CP I CMS | 


Setting | Can set only one address stop at a time. | Can set up to 16 address stops| 
address | | at a time. I 
stops. | | | 


Dumping | The dump is printed in hexadecimal format | The dump is printed in hexa- | 

contents | with EBCDIC translation. The storage ad- | decimal format. The storage | 

of storage I dress of the first byte of each line is | address of the first byte of | 

to the | identified at the left. The control blocks | each line is identified at the| 

printer. | are formatted. | left. The contents of general | 

| | and floating-point registers | 

| I are printed at the beginning | 

| I of the dump. | 


Displaying! The display is typed in hexadecimal format | The display is typed in hexa— | 
the con- | with EBCDIC translation. The CP command | decimal format. The CMS com- | 
tents of | displays storage keys, floating— point regi-| mands do not display storage | 
storage | sters and control registers. I keys, floating-point registersl 
and | | or control registers as the CP | 
control | | command does. | 
registers | | | 
at the | | | 
terminal. | I I 


Storing | The amount of information stored by the CP | The CMS command stores up to | 
informa- | command is limited only by the length of | 12 bytes of information. CMS | 
tion. | the input line. The information can be | stores data in the general | 
| fullword aligned when stored. CP stores | registers but not in the | 
| data in floating-point and control regis- | floating-point or control reg-| 
| ters, as well as in general registers. CP | isters. CMS stores data in the| 
| stores data in the PSW, but not in the CAM | PSW, CAW, and CSW. I 
| or CSW. However, data can be stored in the | I 
| CSW or CAW by specifying the hardware ad- j i 
| dress in the STORE command. | | 


Tracing | CP traces: I CMS traces all SVC interrupts.! 
informa- | • All interrupts, instructions, and | CMS displays the contents | 
tion. | branches I of general and floating-point | 
| • SVC interrupts I registers before and after | 
| • I/O interrupts I a routine is called. The para-| 
| • Program interrupts I meter list is recorded before | 
| • External interrupts I a routine is called. | 
| • Privileged instructions | | 
| • All user I/O operations I I 
| • Virtual and real CCW»s | | 
| • All instructions I | 

| The CP trace is interactive. You can stop | | 
| it and display other fields. | | 



Figure 45. Comparison of CP and CMS Facilities for Debugging 
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Appendix C: Using the CMS Batch Facility 



The CMS Batch Facility is a VM/370 programming facility that runs under 
CMS. It allows a VM/370 user to run jobs in batch mode by gueuing jobs 
from either his own virtual machine or the real card reader to a virtual 
machine dedicated to running batch jobs under the Batch Facility. The 
Batch Facility machine then executes these jobs, freeing the user's 
machine for other uses* The accounting routines charge the time used in 
the batch machine to the originating user. 

The Batch Facility virtual machine is generated and controlled at a 
terminal console under a userid dedicated to execution of jobs in batch 
mode. The system operator generates a batch machine by performing an 
IPL of CMS, then entering a command (CMSBATCH) , which specifies that the 
machine is to execute jobs in batch mode. After each job is executed, 
the Batch Facility reloads itself, thereby providing a continuously 
running batch machine. Jobs are gueued to the batch machine's virtual 
card reader from either user terminals or the system card reader and 
executed sequentially. When its virtual reader is empty, the Batch 
Facility waits for more input. 

The Batch Facility is designed for the non-CMS user who requires a 
system for compiling or executing batch jobs loaded from the real system 
card reader. The Batch Facility is also useful for the interactive user 
who has compute-bound jobs such as assemblies and compilations, and for 
execution of large user programs. This allows interactive users to 
continue work at their terminals while their time-consuming jobs are run 
in another virtual machine. 

Execution time for CP and CMS commands under the Batch Facility is 
equivalent to that of commands typed in at a terminal during an 
interactive CP/CMS session. 



Using the Batch Facility Virtual Machine 

The Batch Facility is generated on any terminal attached to the VM/370 
system. The userid used to run the Batch Facility should be known by 
all users in the installation. 

The interactive users of the Batch Facility must spool their batch 
jobs to the virtual reader of the batch userid and the non-interactive 
users must precede the real deck of batch jobs with a CP ID card 
specifying the userid of the Batch Facility virtual machine. The ID 
card takes the form: 



ID userid 



where ID must begin in card column one and be separated from userid (the 
Batch Facility virtual machine userid) by one or more blanks. 
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INPUT TO THE BATCH FACILITY VIRTUAL MACHINE 

Any user application or development program written in a language 
supported by VM/370 may be executed on the Batch Facility virtual 
■achine. However, there are restrictions on programs using certain CP 
and CHS commands, as described later in this section. 

Programs to be executed under the Batch Facility must be delimited by 
/JOB, and /* control cards. Another control card, the /SET card, may 
also be used with an input program to set certain limits on the 
execution of the program. 

Input records for the Batch Facility must be in card-image format. 
Any record not in card-image foriat is flushed. 

The /JOB and /* Cards 

The /JOB card identifies the name and userid of a job and provides 
accounting information for the system. A /JOB card must precede each 
job to be executed under the Batch Facility. It takes the form: 

i — -■■- 1 

| /JOB userid accntnum [ jobname ] [comments] I 

i _ i 

where: 

userid specifies the user identification of the user who sent the job 
to the batch machine. This userid is charged by the CP 
accounting routines for the system resources used during a 
job. 

accntnum is the user's account number. This account number appears in 
the accounting data that is generated at the end of a user's 
job. This account number will override the account number in 
the CP directory entry for that userid. 

jobname is an optional parameter that specifies the name of the job 
being run. 

comments may be any information the user wishes. 

The userid and jobname parameters are used by the Batch Facility for 
printing of distribution codes for spooled output and for directing job 
status messages to the interactive user's terminal. 

The /* card indicates the end of a job to the Batch Facility. It 
takes the form: 

I /* I 

i i i 

The Batch Facility treats all /* cards after the first as null cards. 
Therefore, if you want to ensure against the previous job not having a 
/* end-of-job indicator, you should precede your /JOB card with a /* 
card. 

The only exception to the way the Batch Facility handles the /* cards 
is in the case of the CHS HOVEFILE command. When the input FILEDEF 
specifies a terminal read, for example FILEDEF INFILE TERM, a /* card 
must be supplied by the user to delimit that file. 
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The /SET Card 

The /SET card sets limits on a system's time, printing, and punching 
resources during the execution of a job. It takes the form: 



i ■ ' 1 

| /SET [TIME seconds] [PRINT lines] [PUNCH cards] | 

i 1 



where: 

seconds is a decimal value that specifies the maximum number of 
seconds of virtual CPU time a job can use. 

lines is a decimal value that specifies the maximum number of lines 
a job can print. 

cards is a decimal number that specifies the maximum number of cards 
a job can punch. 

The default values for the Batch Facility are set at 32,767 seconds, 
printed lines, and punched cards per job. Any new limits defined using 
the /SET card must be less than these maximum settings. The system 
resources can be set at lesser values than the default values by an 
installation's system programmer; be sure you know the maximum 
installation values for batch resource limits before you use the /SET 
card. 



IIJC Files a§ Input 

EXEC files can be used as input to the Batch Facility virtual machine, 
providing a greater level of programming flexibility for Batch Facility 
users. The following list shows a few of the uses for EXEC files in 
manipulating the batch machine. EXEC files can be used: 

• To store control statements (/JOB, /*, and /SET) required for 
execution of queued jobs. 

• To substitute keyword values into a program so that the program can 
be given variable input. 

• To skip over portions of programs using conditional EXEC control 
statements. 

• To identify other EXEC files to be used during program execution. 

• To integrate many files into a single file for execution under the 
Batch Facility. 

The uses of EXEC files in manipulating the input to the Batch 
Facility virtual machine are limited only by the programmer's 
imagination and the rules for writing EXEC files. For rules for writing 
EXEC files and how they can be used, see the VM/370: EXEC User's Guide. 
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Restrictions on CP and CHS C omm ands in Batch Mode 

The Batch Facility permits the use of most CP and CHS commands. The 
exceptions are noted in the following lists. 

Only the following CP commands are allowed to control the Batch 
virtual machine: 



CHANGE* 


HS6 


CLOSE* 


QUERY 


DETACH* 


REWIND 


DOHP 


SPOOL* 


DISPLAY 


STORE 


LINK3 


TAG 



The following CHS commands are disabled under the Batch Facility: 

SET 

READCARD 
DISK LOAD 

The FILEDEF command is also disabled for use in defining the virtual 
card reader. 



BATCH FACILITY OUTPUT 

The Batch Facility's virtual machine runs with its output spooled to the 
terminal console and to the printer. If the batch machine's virtual 
console is connected, CP messages are also printed at the console. The 
printed copy resulting from execution of a program is printed at the 
real printer under the submitting userid, with the user's distribution 
code and a spool file name and type of CHSBATCB JOB (unless a job name 
was specified on the /JOB card) . CHS console output is spooled to a 
file that is printed following the user's program execution output at 
the real system printer, with the submitting user's distribution code, a 
spool filename of BATCH, and a spool filetype of CONSOLE. 

Since all the closed printer files are gueued for system output under 
the submitting userid, the submitting user can control (CHANGE, PURGE, 
I or ORDER) these files before processing on the system printer. 

At job termination, all spooling devices are closed and all files are 
I released. If the CP TAG command was used to identify spool files or to 
| direct these files to other virtual machines or remote work stations, 
I the Batch Facility resets the spooling devices for the next job. If 

disk devices were linked to during the job, they are detached by the 

Batch Facility at job termination time. 

The Batch Facility CHS system is then reloaded, reinitializing all 
nucleus data areas and work areas in storage. 

Also at the end of the job, accounting information is punched to the 
system card punch. This accounting information is in the same format as 
CP/CHS accounting information. 



*Hay not be used to affect the virtual card reader. 

2 Hay not be used to affect spooling devices or the system or IPL disks. 

3 Hust be in the following format: 

CP LINK userid vaddr vaddr mode password 
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Error Recovery 

When a user job terminates abnormally, the Batch Facility sends an ABEND 
message in the appropriate userid terminal console , types the message to 
the BATCH CONSOLE file, and spools a CP dump of the virtual machine 
(with a heading of userid and jobname) to the printer. The Batch 
Facility then performs the normal cleanup tasks and starts the next 
job. 

Since the Batch Facility reloads itself (via IPL) after each job, 
that portion of a job following an ABEND is treated as a new job, which 
is subsequently flushed. 
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Appendix D: CMS Macro Instructions 



The macro definitions that are used by the Conversational Monitor System 
(CHS) are contained in the files CHSLIB HACLIB and OSHACRO HACLIB, which 
reside on the system disk. CMSLIB MACLIB contains the macros which 
provide linkages to the CHS function routines, and OSHACBO HACLIB 
contains Operating System macros which are simulated by CHS. Only the 
CHS macros are discussed in this section. To obtain a list of the names 
and locations of macro definitions in a macro library called libname 
HACLIB, the command HACLIB HAP libname may be issued. 

The macros described in this section deal primarily with linkage to 
the disk and terminal handling routines. WBTERH and BDTEBH handle 
terminal input/output, and FSCB, FSSTATE, FSOPEN, FSREAD, FSWRITE, 
Fs ERASE, and FSCLOSE handle I/O to disk. The offline unit record 
devices may be accessed from an Assembler Language program by using 
RDCABD, PRIHTL, and PUHCHC. 

The IRTERH and RDTERH macros each set up a parameter list inline, and 
issue a CHS supervisor call. For disk I/O, the parameter list is set up 
in a constant area by the FSCB (File system Control Block) macro, or 
generated inline if the FSCB option is not specified. The label of that 
macro is used as a parameter of the FSWRITE, FSREAD, FSOPEN, and FSSTATE 
macros. The example in Figure 46 shows a typical sequence for writing 
and reading disk files. 

The program example in Figure 46 shows the use of I/O macros. The 
program copies a file, the "input file,** to a new file, the "output 
file." If the program were processed by GEHHOD into a module named 
BEGIN, it would be invoked with a command line of the form: "BEGIN FILE1 
EXEC A1 FILE2 EXEC A1," which would copy FILE1 EXEC (input file) to 
FILE2 EXEC (output file) . 

The FSSTATE macro determines the existence of the input file. The 
error branch will be taken if it does not exist. This is not needed for 
the output file, since, if it didn't exist, it would be created. If the 
output file already existed, the new records would be appended to it. 

The program then alternates between reading and writing records, 
until FSREAD returns an error code. Control then goes to EOF, which 
tests whether end-of-file or some other error occurred. If it was 
end-of-file, a return code of zero is passed back to the command level 
in register 15. 

If an error occurs, an appropriate response is typed using the NRTERH 
or LINEDIT macros. Use of the LINEDIT macro at ERR2 and ERR3 causes the 
value of the return code from FSREAD or FSWRITE to be substituted, in 
decimal, for the dots in the text of the message to be typed. 

Note that, if desired, the FSOPEN and FSCLOSE macros could have been 
used to open and close the files. It was not necessary to do so in this 
program because the FSRBAD and FSWRITE macros open the file to be read 
or written. The CHS system automatically closes all files at the end of 
each command execution. 
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STHT 



SOORCB STATEHENT 



1 BEGIN CSECT 

2 PRINT NOGEN 

3 SAVE (14,12),,* 

8 BALE 12,0 ESTABLISH ADDRESSABILITY 

9 USING *,12 

10 LA 2,8(,1) R2=ADDR OF INPUT FILEID IN PLIST 

11 LA 3,32 (,1) R3=ADDR OF OUTPUT FILEID IN PLIST 

12 * DETERMINE IF INPUT FILE EXISTS 

13 FSSTATE (2) ,ERROR=ERR1 

28 * READ A RECORD FROM INPUT FILE AND WRITE ON OUTPUT FILE 

29 RD FSREAD (2) ,ERROR=EOF,BUFFER=BUFF 1,BSlZE=80 
52 FSWRITE (3) ,BRROR=ERR2,BUFFER=BUFF1 ,BSIZE=80 
75 B RD LOOP BACK FOR NEIT RECORD 

77 * COME HERB IF ERROR READING INPUT FILE 

78 BOF C 15,=FM2« END OF FILE ? 

79 BNE ERR3 ERROR IF NOT 

81 RETURN (14,12),RC=0 

85 * IF INPUT FILE DOES NOT EXIST 

86 ERR1 WRTERH 'FILE NOT FOUND* , EDIT=YES 
96 B ERRET 

98 * IF ERROR WRITING FILE 

99 ERR2 LR 10,15 SAVE RET CODE IN REG 10 

100 LINEDIT TEXT=«ERROR CODE IN WRITING FILE* ,SUB= (DEC, (10) ) 

115 B ERRET 

117 * IF READING ERROR WAS NOT NORMAL END OF FILE 

118 ERR3 LR 10,15 SAVE RET CODE IN REG 10 

119 LINEDIT TEXT=*ERROR CODE IN READING FILE 1 ,SUB= (DEC, (10) ) 



135 ERRET 

141 BUFF1 

142 

143 

144 

145 

146 

147 



RETURN (14,12),RC=1 RETURN TO CALLER 



DS 
END 



CL80 

=CL8«RDBUF« 

=CL8«WRBUF« 

=A(BUFF1) 

=F«80« 

=F»12» 



Figure 46. A Sample Listing of a Program that Uses CHS Macros 
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COHPSWT MACHO 

COMPSWT Macro 

PURPOSE: 

The COMPSWT macro causes the COMPSWT flag in the OSSFLAGS byte of the 
Nucleus Constant Area to be turned on or off. 

FORMAT; 

i " ' — i 

I [label] | COMPSWT | ON | OFF I 



OSAGE: 

The compiler switch flag COMPSWT in the Nucleus Constant Area determines 
whether the OS macros LINK, LOAD, XCTL, and ATTACH will use the CHS 
INCLUDE command or the CHS LOADMOD comiahd. With COHPSWT off, the 
program called by LINK, LOAD, XCTL, or ATTACH must be a relocatable 
object module residing in a file with the filetype TEXT or TXTLIB. It 
is called via the INCLUDE command. With COHPSWT on, the program called 
by LINK, LOAD, XCTL, or ATTACH must be an absolute core— image module in 
a file with the filetype HODULE. It is called via the LOADHOD command. 
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PSCB MACRO 



FSCB Macro 

PURPOSE : 

The FSCB macro creates a File system Control Block, which is used as the 
parameter list to the file system routines. 

FORMAT : 

i 1 

| [label] | FSCB | [fileid] [ ,RECFM=f ormat ] | 

| | | [ ,BUFFER=buffer] [ ,BSIZE=size ] | 

| | | [ ,RECNO=number ] [ ,NOREC=numrec] | 

i i 

label is an optional statement label. 

fileid specifies the file identifier enclosed in quote marks and 
separated by blanks ('filename filetype filemode 1 ) . If 
filemode is omitted, "A1" is assumed. 

format F indicates fixed-length records (default) . 
V indicates the variable-length records. 

buffer specifies the address of the I/O buffer. 

size specifies the size of the buffer in bytes. 

number specifies the relative record number of the next record to be 
accessed (default = 0) . 

numrec specifies the number of records to be read (default = 1) . 

Note: The above options must be specified as self-defining terms. 

USAGE : 

The FSCB macro generates a File System Control Block for the specified 
file. It may be used as the parameter list to the file system 
routines. 

15 JO R_ CON DI T 10 N S : 

Errors in macro operand coding will cause Assembler errors. 
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FSCLOSE MACRO 



FSCLOSE Macro 



PURPOSE: 



The FSCLOSE macro causes an open file to be closed and its current 
status saved on the disk. 



FORMAT: 



|[label]| FSCLOSE | [ f ileid ] [,FSCB=fscb] [ ,ERROR=erraddr ] | 



label 
fileid 



fscb 



erraddr 



is an optional statement label. 

specifies the file identifier. •fileid* may be coded even if 
FSCB= is also specified. It may be: 

' f n ft fm* fileid enclosed in guote marks and separated by 
blanks. If fm is omitted, "A1" is assumed. 

(reg) a register from 2 to 15 containing the address of 
the fileid (18 characters). 

specifies the address of an FSCB. It may be: 



label 
(reg) 



the label on the FSCB macro. 

a register containing the address of an FSCB. 



specifies the address of an error routine to be given control 
if an error is encountered. If ERROR= is not coded, control 
returns to the next sequential instruction in the calling 
program if an error occurs, as it does if no error occurs. 



OSAGE: 

FSCLOSE should be used within EXEC procedures to close files that are no 
longer needed for processing. The FSCLOSE macro causes the specified 
file to be closed. Either a fileid or FSCB must be specified. 

I1I2S-C ND ITI MS : 

If an error occurs, processing terminates, and control is passed to 
erraddr (if one was provided) or back to the calling program's next 
sequential instruction. Register 15 contains the following error code: 

Code Meaning 
6 File not open 
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FSERASE MACRO 



FSERASE Macro 



PURPOSE: 

The FSERASE macro causes one or more files to be deleted from the user»s 
disk. 



FORMAT: 



|[label]| FSERASE |[ f ileid ][ r FSCB=fscb][ ,ERROR=erraddr ] | 

i 1 

label is an optional statement label. 

f ileid specifies the file identifier. * f ileid 1 may be coded even if 
FSCB= is also specified. It may be: 

'fn ft fm' f ileid enclosed in quote marks and separated by 
blanks. If fm is omitted, "A1" is assumed. 

(reg) a register other than or 1 containing the 
address of the f ileid (18 characters) . 

fscb specifies the address of an FSCB. It may be: 

label the label of an FSCB macro. 

(reg) a register containing the address of an FSCB. 

erraddr specifies the address of an error routine to be given control 
if an error is encountered. If ERROR= is not coded, control 
returns to the next sequential instruction in the calling 
program if an error occurs, as it does if no error occurs. 

USAGE: 

The FSERASE macro causes the specified file to be deleted from the 
user's disk. Either a f ileid or FSCB must be specified. 

ERR0g_C01jDITI0HS : 

If an error occurs, register 1 points to the FSCB for the file having 
the error and register 15 contains one of the following error codes: 

Code Meaning 
24 Parameter list error 
28 File not found 
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FSOPEN MACRO 



FSOPEN Macro 



PURPOSE: 



The FSOPEN macro causes the file to be made ready for either input or 
output. 

FORMAT: 



j [label] | FSOPEH | [fileid] [ ,FSCB=fscb] [, options] | 
I | | [ ,ERROR=erraddr] | 

i i 



label 
fileid 



fscb 



is an optional statement label. 

specifies the file identifier. 'fileid* may be coded even if 
FSCB= is also specified. It may be: 

• f n ft fm' the fileid enclosed in guote marks and separated 
by blanks. If fm is omitted, "A1" is assumed. 

(reg) a register other than or 1 containing the 
address of the fileid (18 characters) 

specifies the address of an FSCB. It may be: 



label 
(reg) 



the label on an FSCB macro. 

a register containing the address of an FSCB. If 
FSCB= is not coded, an fscb is created inline, 
pointed to by register 1 , upon return from the 
macro call. 



options any of the options of the FSCB macro instruction may be 
specified here. Only the BUFFER, RECNO, NOREC, and BSIZE 
(variable file only) options have any effect for an already 
existing file. These options may be specified as either a 
self-defining term or a register enclosed in parentheses. 

erraddr specifies the address of an error routine to be given control 
if an error is encountered. If ERROR= is not coded, control 
returns to the next seguential instruction in the calling 
program if an error occurs, as it does if no error occurs. 

USAGE: 

The FSOPEN macro causes the FSCB to be filled in from the file status 
table for an already existing file. A file status table entry is 
created for a new file. Either a fileid or FSCB must be specified. On 
return, register 1 points to the FSCB for the file. 

FSOPEN is used mainly to determine the existence of the file about to be 
processed. 

ERROR CONDITIONS : 

If an error occurs, processing terminates, and control is passed to 
erraddr (if one was provided) or back to the calling program's next 
seguential instruction. Register 15 contains one of the following error 
codes : 

Code Meaning 
28 File does not exist 
20 Invalid file identifier 
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PSREAD MACRO 

FSREAD Macro 

PURPOSE: 

The FSREAD macro causes a record to be read from disk, 

FORMAT: 



I [label] | FSREAD | [fileid] [,FSCB=fscb] [, options] | 
I | | [ ,ERROR=erraddr] I 



label 
fileid 



f scb 



options 



erraddr 



is an optional statement label. 

specifies the file identifier. 'fileid* may be coded even if 
FSCB= is also specified. It may be: 

'fn ft fm' the fileid enclosed in guote marks and separated 
by blanks. If fm is omitted, "A1" is assumed. 

(reg) a register other than or 1 containing the 
address of the fileid (18 characters). 

specifies the address of an FSCB. It may be: 



label 
(reg) 



the label of an FSCB macro. 

a register containing the address of an FSCB. 



the BUFFER, NOREC, BSIZE, and RECNO options of the FSCB macro 
instruction may be specified here. If the FSCB parameter is 
omitted, the BUFFER and BSIZE options must be specified. 
These options may be specified as either a self-defining term 
or a register enclosed in parentheses. 

specifies the address of an error routine to be given control 
if an error is encountered. If ERROR= is not coded, control 
returns to the next sequential instruction in the calling 
program if an error occurs, as it does if no error occurs. 



USAGE: 

The FSREAD macro reads one record into the user's buffer. If the RECNO 
option is specified, that specified record is read. Otherwise, the next 
record in the file is read. If RECNO is specified, it must be reset to 
zero by the next FSREAD in order to read the file sequentially from the 
originally specified record number. Either a fileid or FSCB must be 
specified. On return, register contains the number of bytes read. 
Register 1 points to the FSCB. 

II ROR_C PJDITI NS : 

If an error occurs, processing terminates, and control is passed to 
erraddr (if one vas provided) or back to the calling program's next 
sequential instruction. Register 15 contains one of the following error 
codes: 

Code Meaning 

1 File not found 

2 Invalid buffer address 

3 Permanent I/O error 
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FSREAD MACRO 



Code Meaning 

5 Number of records is less than or equal to zero, or 
greater than 32768 

7 Invalid record format (only checked for at the first read 

after finis or ipl) 

8 Incorrect length 

9 File open for output 

11 Number of records greater than 1 for variable length file 

12 End of file 

13 Variable length file has invalid displacement in active 

file table 

14 Invalid character in filename 

15 Invalid character in filetype 
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FSSTATE MACRO 
FSSTATE Macro 

PURPOSE: 

The FSSTATE macro returns to the user the current status of the 
specified file. 

FORMAT: 

•i 1 

|[Iabel]| FSSTATE | [fileid] [ ,FSCB=fscb] [ f ERROR=erraddr ] | 

i 1 

label is an optional statement label. 

fileid specifies the file identifier. 'fileid 1 may be coded even if 
FSCB= is also specified. It may be: 

•fn ft fm' the fileid enclosed in quote marks and separated 
by blanks. If fm is omitted, n A1" is assumed. 

(reg) a register other than or 1 containing the 
address of the fileid (18 characters) . 

fscb specifies the address of an FSCB. It may be: 

label the label on an FSCB macro. 

(reg) a register containing the address of an FSCB. 

erraddr specifies the address of an error routine to be given control 
if an error is encountered. If ERROR- is not coded, control 
returns to the next sequential instruction in the calling 
program if an error occurs, as it does if no error occurs. 

USAGE: 

The FSSTATE macro causes the existence of the specified file to be 
verified. Register 1 points to a copy of the File Status Table (FST) 
for the specified file. Either a fileid or FSCB must be specified. 

ERROR CONDITIOHS : 

If an error occurs, processing terminates, and control is passed to 
erraddr (if one was provided) or back to the calling program's next 
sequential instruction. Register 15 contains one of the following error 
codes: 

Code Meani ng 

20 Invalid character in fileid 

24 Invalid filemode 

28 File not found 

36 Disk not accessed 



372 IBM VM/370: Command Language Guide for General Users 



FSHRITE MACRO 



PURPOSE: 

The FSHRITE macro causes a record to be written to the disk. 

FORMAT: 

L] | FSWRITE 

| [ , ERROR=erraddr ] 

i 1 

label is an optional statement label. 

fileid specifies the file identifier. 'fileid* may be coded even if 
FSCB= is also specified. It may be: 

* f n ft fm" the fileid enclosed in quote marks and separated 
by blanks. If fm is omitted, "A1" is assumed. 

(reg) a register other than or 1 containing the 
address of the fileid (18 characters) . 

fscb specifies the address of an FSCB. It may be: 

label the label on an FSCB macro. 

(reg) a register containing the address of an FSCB. If 
FSCB= is not coded, BUFFER= and BSIZE= must be 
coded. 

options any of the options of the FSCB macro instruction may be 
specified here. Only the BUFFER, RECMO, and BSIZE options 
have any effect on an already existing file. These options 
may be specified as either a self-defining term or a register 
enclosed in parentheses. 

orr ad/lr o ri a r* -i -f- -1 c* o +■ V» e± o A A "£Q e? c q£ o r\ grr rtr " rOUtinO tO be dVeU COntrOi 

if an error is encountered. If ERROR= is not ceded, control 
returns to the next sequential instruction in the calling 
program if an error occurs, as it does if no error occurs. 

USAGE: 

The FSWRITE macro writes one record onto the user's disk. If the RECNO 
option is specified, that specified record is written. Otherwise, the 
next sequential record in the file is written. 

To write a file beginning with a specific record in the file, two 
FSHRITE statements must be issued: the first to specify the record 
number where the writing is to begin, for example, RECN0=5 begins the 
write operation at record number 5 in the specified file. The second 
FSHRITE statement must set the RECNO option to zero, which will cause 
the remaining records in the file to be written sequentially. Either a 
fileid or FSCB must be specified. On return, register 1 points to the 
FSCB for the file. 

Using the BSIZE option of the FSCB macro, you can write multiple records 
in a single FSHRITE statement. For example, if you wish to write 20 
records at once, you code BSIZE=1600 (the length of the record times the 
number of records) . Variable length records cannot be written like this, 
however. They must be written sequentially each with its own lenqth 
specified. 
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GC20-1804-3 Page Modified by THL GN20-2659 
FSHRITE MACRO 

ESBQR_CQNDITIOH S : 

If an error occurs, processing terminates, and control is passed to 
erraddr (if one was provided) or back to the calling program's next 
sequential instruction. Register 15 contains one of the following error 
codes: 

Code Meaning 

2 Invalid buffer address 

4 First character of filemode is illegal 

5 Second character of filemode is illegal 

6 Item number too large 

7 Attempt to skip over unwritten variable length item 

8 Buffer size not specified 

9 File open for input 

10 Maximum number files reached 

11 Record format not F or V 

12 Attempt to write on read-only disk 

13 Disk is full 

15 Length of fixed length item not the same as previous item 

16 Record format specified not the same as file 

17 Variable length item greater than 65K bytes 

18 Humber of records greater than 1 for variable length file 

19 Maximum number of data blocks per file reached (16060) 

20 Invalid character detected in filename 

21 Invalid character detected in filetype 



374 IBM VM/370: Command Language Guide for General Users 



HNDEXT MACRO 



HNDEXT Macro 



PURPOSE: 



The HNDEXT macro causes external interrupts to be passed to the user's 
routine for processing. 

FORMAT: 



| [label] | HNDEXT | function[ , address ] | 

i. „ ., i 

label is an optional statement label. 

function specifies whether the interrupts are to be trapped (SET) or 
cleared (CLR) . 

address specifies the address of the routine to process the 
interrupts. This parameter is required only when the SET 
function is specified. 

OSAGE : 

The HNDEXT macro causes CMS to pass control to the user's routine when 
an external interrupt occurs. When the user is given control, all 
virtual interrupts except multiplexer are disabled. On entry to the 
user's routine, register 1 points to a save area used for saving the 
registers and PSW at the time of the external interrupt, starting at 
label GRS, as shown below. Register 13 points to an 18-fullword save 
area starting at label UAREA, shown below. Register 14 contains the 
address the user's routine must return to when this processing is 
complete, and register 15 contains the address of the user's processing 
routine. After HNDEXT CLR is issued, an external interrupt other than a 
timer interrupt will cause DEBUG to be entered. 

SAVE AREA FORMAT: 

Displacement 



GRS 








FRS 


64 


40 


PSW 


96 


60 


UAREA 


108 


68 


END 


180 


B4 



ERROB CONDITIONS : 
None. 
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HNDINT MACRO 



HN DINT Macro 

PURPOSE : 

The HNDINT macro causes interrupts for the specified devices to be 
passed to the user's routine for processing. 

FORMAT: 

i 1 

| [label] | HNDINT | function, (devname[ , address, devaddr, when ]) . . . j 

I | | [ ,ERROR=erraddr] I 

i i 

label is an optional statement label. 

function specifies whether the interrupts are to be trapped (SET) or 
cleared (CLR) . 

devname specifies a four character symbolic name for the device. 

address specifies the address of the routine to process the 
interrupts. An address of zero indicates interrupts for the 
device are to be ignored. 

devaddr specifies the device address, in hexadecimal, of the device 
whose interrupts are to be trapped. 

when specifies that the interrupts are to be reflected immediately 
(ASAP) or only after the WAITD macro is issued (WAIT) . 

erraddr specifies the address of an error routine to be given control 
if an error is encountered. If ERROR= is not coded, control 
returns to the next sequential instruction in the calling 
program if an error occurs, as it does if no error occurs. 

Note: address, devaddr, and when need not be specified if CLR is 
specified. 

OSAGE : 

The HNDINT macro causes CMS to pass control to the user's routine when 
an interrupt is received from one of the specified devices. The user 
routine will be entered immediately if ASAP is specified or a WAITD 
macro has been issued for the device. If neither condition exists, the 
interrupt will be stacked, until a WAITD macro is issued for the 
device. When the user is given control, all I/O interrupts and external 
interrupts are disabled. On entry to the user's routine, registers and 
1 contain the I/O old PSW, registers 2 and 3 contain the CSW, register 4 
contains the interrupting device address, register 14 contains the 
address that the user's routine must return to when his processing is 
complete, and register 15 contains the address of the user's processing 
routine. When processing is complete, the user must return to CMS via 
register 14 and indicate in register 15 whether processing is complete. 
A zero in register 15 indicates that the user has completed handling the 
interrupt and a nonzero register 15 indicates that another interrupt is 
expected. The CLR function indicates that the user is finished 
processiing interrupts for this device. For additional information, see 
the documentation for WAITD. 

ERROR CONDITIONS : 

If an error is detected, register 15 contains a 1, indicating that the 
devaddr or address is invalid. 
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HNDSVC MACRO 

HNDSVC Macro 

PURPOSE: 

The HNDSVC macro causes interrupts for the specified supervisor call 
(SVC) numbers to be passed to the user's routine for processing. 

FORMAT : 

i 1 

| [label] | HNDSVC | {set |clr },{ (svcnum, address) | svcnum } | 
I | | [,{ (svcnum, address) Isvcnum}]. . . | 

| | | [ ,ERROR=erraddr ] j 

i . i 

label is an optional statement label. 

svcnum specifies a number from to 200 or 206 to 255 that 
corresponds to the SVC number to be handled by the user 
routine. (SVC's 204 and 205 are reserved for future use.) 

address specifies the address of the routine to process the 
interrupt. This field need not be specified with the CLP. 
function. 

erraddr specifies the address of an error routine to be given control 
if an error is encountered. If ERR0R= is not coded, control 
returns to the next seguential instruction in the calling 
program if an error occurs, as it does if no error occurs. 

USAGE: 

The HNDSVC macro causes CMS to pass control to the user's routine when 
one of the specified SVC instructions is issued. On entry to the user's 
routine the following conditions exist: 



n^-n*-~r. 4-ct 



Register 

___ _»Uii_.cii to 

0-11 and 15 As they were when the SVC was executed. 

12 Address of user SVC handler routine. 

13 Address of an 18-fullword save area for use by the 

user's SVC handler routine. 

14 Return address in CMS. 

The user must return to CMS via register 14 when he has completed 
processing the interrupt. The CLR function indicates that the user is 
finished handling interrupts for the specified SVC number. 

I JJO JL CON DI T ION S : 

If an error occurs, processing terminates, and control is passed to 
erraddr (if one was provided) or back to the calling program's next 
seguential instruction. Register 15 contains one of the following error 
codes: 

Code Meaning 

1 Invalid SVC number or address 

2 SVC number set replaced previously set number 

3 SVC number cleared was not set 
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LINEDIT Macro 



PURPOSE: 



The LINEDIT macro provides a method for performing conversions into 
EBCDIC, and, optionally, typing the results at the terminal. 

FORMAT: 



[label] 



LIHEDIT 



MF=I|L| (E,addr) | (E, (reg) ) ] 

, TEXT=» message— text 1 ] 

,TEXTA=address | (reg) ] 

,COMP=YES|NO] 

,DOT=YES|NO] 

,SOB=(type,value[ , type, value ].. ) ] 

,DISP=TYPE| NONE |SIO| PRINT |CPCOHM] 

,BUFFA=address| (reg) ] 

,RENT=YES|NO ] 

,MAXSUBS=number] 



where the option list consists of the following keyword parameters 
(described in greater detail in the section on "LIHEDIT Macro 
Parameters") : 

MF=I|L| (E,addr) | (E, (reg) ) to specify macro form 

TEXT =I message- text* to specify message text 

TEXTA=address | (reg) to specify message text address 

COMP=YES|HO to suppress multiple blank compression 

DOT=YES|NO to suppress final period on message text 

SDB= (type, value[ , type, value ].. .) to specify a substitution list where: 

type = HEX 
= HEXA 
= DEC 
= DECA 
= HEX4A 
= CHARA 
= CHAR8A 

value= expression 
= (reg) 
= address 

= (address, length) length being egual either 
to number or (reg) 

DISP=TYPE INQNE | SIO IPBINT ICPCOMM to specify the action to be taken with 
message text. 

BDFFA=address| (reg) to specify return buffer address 

RENT=yes|no to specify whether reentrant code must be generated. 

MAXSOBS=number to specify the maximum number of substitutions with 
MF=L. 

Bote: Registers 1 and 15 should not be used as argument registers to the 
LINEDIT macro; they are used as work registers by the macro. 
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LIHEDIT MACHO 



LINEDIT MACRO PAHAMETEBS 



MF Parameter 



The HF parameter specifies whether the form of the macro is to be 
standard, list, or execute. This parameter is coded as follows: 

MF=I|L| (E,addr) | (E, (reg) ) 

with the following meanings: 

MF=I (Standard form) 

This is the most usual form, and the default. It generates an inline 
PLIST, and generates a call to the LINEDIT routine so that the 
message will be typed at the terminal. 

The standard form will generate only reentrant code, and may be used 
under all circumstances except the following: 

• If more than one substitution is made. 

• If TEXTA= (reg) is used. Note that TEXTA=address can be used in 
the standard form, with the address referenced in the PLIST by an 
address constant. 

• If the BOFFA parameter is used. 

MF=(E,addr) or MF=(E,(reg)) (Execute form) 

If used in this form, the macro will generate code to construct a 
PLIST at the specified address, rather than using an inline PLIST. 
The code will then call LINEDIT, passing the address of the newly 
constructed PLIST. 

The address of the construction area for the PLIST is given by 

"addr," to specify an address which can be obtained by a Load Address 

(LA) instruction, or by n (reg) ," where the register specified points 
to the area. 

In either case, the specified area must be large enough to construct 
a PLIST. The size of a PLIST is variable, depending upon the number 
of substitutions made, and whether BOFFA was specified. The list 
form of the LINEDIT macro is used to reserve space for the PLIST. 

MF=L (List form) 

This form generates a PLIST only. It does not generate any 
executable code. It is used to reserve space for a PLIST to be 
constructed using the HF=(E,....) execute form. The size of the area 
reserved depends upon the number of substitutions to be made, as 
specified with the MAXSUBS parameter. 

For example, 

LINEDIT MF=L,MAXS0BS=5 

reserves space for a PLIST which may hold up to five substitution 
parameters. 
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LIHEDIT MACRO 

TE XT Parameter 

This parameter specifies the message text as a character string between 
single quotes, single quotes appearing in the message text should be 
coded as two single quotes. This parameter is coded as follows: 

TEXT= ' message-text ' 

If the TEXT Parameter is coded, the TEXTA parameter must not be 
coded. 



2II31 Parameter 

This parameter is an alternative to the TEXT parameter. It specifies 
the address of the message text. The message text consists of a 
one-byte length field, followed by the actual text of the message. The 
parameter is coded as follows: 

TEXTA=address| (reg) 

If used in the standard or list form of the macro, the "address" is 
used in an address constant. The "(reg)" form then may not be used. If 
used in the execute form, the "address" is obtained by a Load Address 
(LA) instruction. If the "(reg)" form is used, then the specified 
register (other than registers 1 and 15) contains the address of the 
message text area. If the TEXTA parameter is coded, the TEXT parameter 
must not be coded. 



COMP Parameter 

This parameter specifies how multiple blanks in the message are to be 
handled. With COMPLIES, the default, the LIHEDIT routine compresses all 
multiple blanks in the message into a single blank. If COMP-NO is 
coded, this compression is not done. 



DOT Parameter 

The DOT parameter indicates whether the end of the message will have a 
period. With DOT=YES, the default, the LINEDIT routine places a period 
(dot) at the end of the message. If DOT s NO is coded, this is not done. 



SUB Parameter 

This parameter is used to specify a substitution list that allows a 
message to have a value substituted into it at execution time. Whenever 
the LINEDIT scanning routine discovers two or more consecutive periods 
in the message text, it assumes that a substitution is to be made. 
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The number of consecutive periods indicates the length (or maximum 
length) of the substituted field, after conversion, if any. The SUB 
parameter is coded as follows: 

SOB= (type, valuer -type, value ] s * s ) 

where each "type, value" pair specifies the type and value of the 
substitution. Possible "type, value" substitutions are: 

HEX, (reg) 

The value in the specified register (other than registers 1 and 15) 
is to be converted to graphic hexadecimal form. If fewer than eight 
consecutive periods are coded in the message text, then leading 
digits will be truncated. Leading zeros are not automatically 
truncated. 

HEX, expression 

The given expression, which will be evaluated by means of a Load 
Address (LA) instruction, is converted as indicated above into 
graphic hexadecimal form. 

HEXA, address 

The "address" specifies a fullword that is to be converted to graphic 
hexadecimal, as above. 

HEXA, (reg) 

The register (other than registers 1 and 15) points to a fullword 
that is to be converted to graphic hexadecimal form, as above. 

DEC, (reg) 

The value in the specified register (other than registers 1 and 15) 
is to be converted to graphic decimal form and inserted into the 
message text. Leading zeros will be suppressed. If the number is 
negative, then a leading minus sign will be inserted. 

DEC, expression 

The given expression, which will be evaluated by means of a Load 
Address (LA) instruction, is converted as indicated above into 
graphic decimal. 

DECA, address 

The "address" specifies a fullword which is to be converted to 
graphic decimal, as above. 

DECA, (reg) 

The specified register (other than registers 1 and 15) contains the 
address of a fullword that is to be converted to graphic decimal, as 
above. 

HEX4A, address or HEX4A,(reg) 

Is used for graphic hexadeciaml dumps of other than fullwords. The 
"address" (or a register other than 1 or 15) points to the first byte 
to be converted to graphic hexadecimal form. A blank is inserted 
into the message text after each four characters of input (eight 
characters of output) have been coverted. Thus, if an 8-byte input 
field (16 hexadecimal digits) is to be converted, 17 periods should 
be coded. The output field length is determined by the number of 
periods in the message text. The length, in bytes, of the field to 
be converted may be specified as follows: 

HEX4A, (address | (reg) , length | (reg)) 
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CHARA, address or CHARA, (reg) The "address" (or a register other than 1 
or 15) points to the first byte of a field that is to be substituted 
as a character string. The output field length is determined by the 
number of consecutive periods in the message text. The length, in 
bytes, of the field to be substituted may be specified as follows: 

CHARA, (address | (reg) ,length| (reg) ) 

CHAR8 A, address or CHAR8A, (reg) Is useful if a string of PLIST arguments 
(for example, a fileid) is to be substituted into the message text. 
LINEDIT will insert a blank after each 8 characters of the 
substitution string. Thus, to substitute an 18-byte fileid, code 20 
periods in the message text, to allow for the inserted blanks. The 
"address" (or a register other than 1 or 15) points to the first byte 
of the input substitution string. The length, in bytes, of the input 
string may be specified as follows: 

CHAR8A, (address| (reg) ,length| (reg) ) 

Note that registers 1 and 15 may not be used for the address or 
length specification. 



P.ISP Parameter 

This option specifies what LINEDIT is to do with the message which it. 
has created. Specifications for the DISP parameter are: 

DISP=TYPE (the default) specifies that the message is to be typed on the 
terminal using TYPLIN. 

DISP-SIO specifies that the message is to be typed at the terminal using 
SIO. This option is necessary if, for example, free storage pointers 
are destroyed. No CONWAIT function is performed. 

DISP=NONE specifies that no output whatsoever is to occur. This option 
is useful with the BOFFA paraneter, described below. 

DISP=PRINT specifies that the line is to be printed on the virtual 
printer. 

DISP=CPCOMM specifies that the line is to be passed to CP to be executed 
as a CP console command. 

DISP-ERRHSG specifies that the line is to be checked to see if it 
gualifies for "error message editing". If it does it is displayed as 
an error message rather than a regular line. 

The first ten characters of the line are the "code" and the rest of 
the line is the "text" of an error message. In a standard VM/370 
error message, the code of an error message is in the following 
format: 

mmmmmmnnnt 

where mmmmmm is the name of the module issuing the message, nnn is 
the message number, and t is the message type. Nith LINEDIT, you can 
code error messages for your own programs. You need not follow the 
VM/370 conventions for the first nine characters of the code, but the 
tenth character must specify a recognized VM/370 message type if 
error message editing is to occur. The recognized types are: 
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Message Type 
IHFORHATION 
WARNING 
ERROR 



Tenth Character of 
Message Line 

I 
w 

E 



If one of these letters is the tenth character in the line, the line 
will be typed in accordance with the current EHSG conditions that are 
controlled by the CP SET EMSG command. If the tenth character is 
anything else, the entire line will be typed as a regular line, with 
no distinction made between code and text. 



BDFFA Parameter 



This parameter specifies the address of a buffer, 
follows: 

BOFPA=address| (reg) 



It is coded 



as 



If a register is specified, it must not be register 1 or 15. 

If this option is specified, then, in addition to the action 
specified by the DISP parameter, the message text is copied into the 
buffer at the specified address. The length of the text is inserted 
into the first byte of the buffer, and the message text into subsequent 
bytes. 



RENT Parameter 



The "standard" form of the LINEDIT macro generates reentrant code unless 
one of the following is true: 

• TEXTA-(reg) is specified. 

• BOFFA= (reg) is specified. 

• More than one substitution pair is specified. 

If reentrant code is not generated, and RENT=YES (the default) is in 
effect, the LINEDIT macro expansion contains an HNOTE statement warning 
the user that nonreentrant code is being generated. If the user does 
not object to nonreentrant code, and does not wish to have the HNOTE 
appear, he should code RENT-NO. The RENT-NO coding merely suppresses 
the HNOTE statement; it has no effect on the expansion of the LINEDIT 
macro. 



HAXSUBS Parameter 



This parameter is used only in the list form (HF=L) of the macro, which 
is used to reserve space. It specifies the maximum number of 
substitutions to be made, so that enough space for those substitutions 
can be reserved. It is coded: 

HAXSUBS=number 
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LIHEDIT CODING EXAMPLES 

The following examples illustrate some options of the LIHEDIT macro. 
Because of the limitations of space, some of the longer coding examples 
appear on two lines. However, normal coding conventions for 
continuation statements should be used in actual coding. 



The simplest use of the LIHEDIT macro is to type a message without any 
substitutions whatsover. 

LIHEDIT TEXTs'THlS IS A LIHE» 

causes the following to be typed out on the terminal when it is 
executed: 

THIS IS A LIHE. 

Hote that multiple blanks are removed from the message, and a period 
is placed at the end of the line. 



The real power of the LIHEDIT macro is in the capability of making 
substitutions. Whenever the LIHEDIT processor finds two or more 
consecutive periods in the message text, it makes a substitution from 
the 'SUB' list provided in the macro call. 

To illustrate the simplest type of substitution, using the DEC 
option, suppose the following is executed: 



LIHEDIT TEXT=«THE VALUE IS • , 

SUB=(DEC,VALUE+5) 

If the Assembler language program contains a statement of the form 
"VALUE EQD 2003", then when this macro is executed, the line, 

THE VALUE IS 2008. 

is typed at the terminal. 



Usually some value computed during execution of the program is 
requested. To type out the contents of a register, the following can be 
used: 

LIHEDIT TEXT** VALUE = • ,SUB= (DEC, (3) ) 

If, when this macro is executed, register 3 contains the decimal 
value 10345, then the following line is typed out: 

VALUE = 10345. 
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Example 4 

The DECA option is used to specify the address of a fullword in storage 
which contains the value to be typed out. The address of evaluated by 
means of a Load Address (LA) instruction. Bxecution of: 

LINEDIT TEXT=» VALUE = • , SOB= (DECA ,LOC) 

vould cause the value in the fullword at location LOC to be typed out in 
decimal format. 

Similarly, the macro call 

LINEDIT TEXT=« VALUE = • ,SUB= (DECA, (3) ) 

would cause the value in the fullword whose address is in register 3 to 
be typed out in decimal. 

Note; As the examples given show, when the keyword (such as DEC) does 
not end in an 'A', then a value is being specified as the next 
argument. When the keyword (such as DECA) does end in 'A', then the 
address of a value is being specified. When the next argument is 
enclosed in parentheses, the value or address is to be found in the 
register, other than 1 or 15, that was specified. 



Example 5 

The number of consecutive periods appearing in the message text is 
usually significant. In DEC and DECA, it indicates the maximum number 
of characters (including the minus sign) which will appear in the 
number. If the number is too large to fit in the field, then high-order 
digits will be truncated. 

To be certain that high-order digits will never be truncated, code 
ten periods in the message text for DEC and DECA, as in: 

LINEDIT TEXT= • VALUE » • , 

SUB=(DBC, (3)) 



Example 6 

The HEX option is similar in use to the DEC option, except that the 
substituted values are typed out in hexadecimal rather than in decimal. 
Execution of: 

LINEDIT TEXT= , »»LOC , » IS LOCATED AT • , 

SUB=(HEX,LOC) 

would cause the value of LOC to be substituted in hexadecimal format, so 
that the following might be typed out: 

«LOC« IS LOCATED AT 0201AC. 
Note that the leading zeros are not removed. 
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Example 7 

Parentheses are used to type out the current value of a register in 
hexadecimal. For example, if register 3 contained the value C0031FC8, 
then the macro 

LINEDIT TEXT=« VALUE = . . . • , SOB= (HEX, (3) ) 

would cause the line, 

VALUE = FC8. 

to be typed out. Hotice that since three periods were specified, just 
the last three hexadecimal digits of the register contents were typed 
out. 

Example 8 

The HEXA option is used if the address of a fullword in storage 
containing the desired value is specified. Execution of: 

LINEDIT TEXT=«HEX VAL = • ,SDB= (HEXA ,VAL) 

will cause the last five hexadecimal digits of the fullword at VAL to be 
substituted into the message text. 

And if 

LINEDIT TEXT=»HEX VAL = • , SUB (HEXA , (5) ) 

is executed, then the last six hexadecimal digits of the fullword whose 
address is in register 5 will be substituted. 

Example 9 

The HEX4A option is used for dumping a variable number of bytes of 
storage on the terminal. The dump has the format: 

hhhhhhhh hhhhhhhh hhhhhhhh hhhhhhhh .... 

where each "h" stands for a hexadecimal digit. The number of periods in 
the message text specifies the size of the output field and, hence, 
indirectly specifies the number of bytes of "input" data to be 
converted. 

Each byte of input data is converted into two hexadecimal digits for 
substitution. After each four bytes of input (eight bytes of output), a 
blank is inserted. Thus, if a dump of seven bytes of data in this 
format is requested, 15 periods must be coded. The extra period is for 
the blank to be inserted. The macro, 

LINEDIT TEXT=» VALUES ARE «, 

SUB= (HEX4A, (6)) 

would cause a line to be displayed as follows: 

VALUES ARE 0A23F115 78ACFE. 

where the values being dumped start at the address that is specified in 
register 6. 
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Example JO 

The CHARA option is used to make a straight character substitution. The 
number of periods indicates the number of characters to be substituted: 

TTHBnTir miTm-iBiiij tq si ; « * 

UJ.HCUX1 1£A1 n a. a El AJ ....... , 

SUB= (CHARA, LOC) 

would cause the seven characters starting at location LOC to be 
substituted into the text, to produce a message such as: 

NAME IS •LOCINDA*. 
Multiple blanks in the substituted string will be removed. 



Example XI 

The CHAR8A option is similar to the CHARA option, except that a blank is 
inserted into the output text after each group of eight characters. 
This is particularly useful for dumping PLISTs, since a blank is 
inserted after each doubleword in the PLIST. For example, 

LINEDIT TEXT=»FILE NOT 

FOUND 1 ,SOB= (CHAR8A,PLIST+8) 

could cause the following output: 

FILE X ASSEMBLE A1 NOT FOUND. 

Note that 20 periods were coded, to include space for the two 
inserted blanks. In the final edited line, multiple blanks are reduced 
to a single blank. If the CHARA option had been used, with 18 periods 
specified, then the same message would have appeared as: 

FILE X ASSEMBLEA1 NOT FOUND. 



Example J 2 

To make several substitutions in a given line, it is necessary only to 
code several groups of periods in the message text, and several pairs of 
substitution values in the SUB parameter list. 

The following macro: . 

LINEDIT TEXT=« VALUES ARE AND ......», 

SUB=(DEC,(3) ,HEXA,LOC) 

would generate a line like the following: 
VALUES ARE -45 AND FFE3C2. 

Each group of periods represents one substitution, and each pair of 
SUB arguments represents one value to be substituted. 
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Example 21 

To reserve space in a work area for a LINEDIT PLIST, the "list" fori of 
the LINEDIT macro (HF=L) must be used. Specifying 

LINLIST LINEDIT MF=L,MAXSUBS=6 

will reserve space for a LINEDIT PLIST, and give that space the label 
•LINLIST 1 . The parameter , MAXSUBS=6 I indicates that enough space is to 
be reserved so that a PLIST with space for six or fewer substitution 
pairs can be built. 

If a larger HAXSUBS value is specified, then a larger amount of space 
is reserved for PLIST contruction. 



Example Hi 

The execute form of the LINEDIT macro does not generate a PLIST as part 
of its expansion, as does the standard form. (Examples 1 through 12 use 
the standard form of the macro.) Instead, the execute form expands to 
create a PLIST in a work area. The space for the PLIST should have been 
reserved using HF=L as indicated in Example 13. To call LINEDIT after 
creating a PLIST in the work area reserved by the LINEDIT macro in the 
last example, the following form could be used: 

LINEDIT MF= (E, LINLIST) , other options ... 

The "other options" may be any of the options discussed in preceding 
examples, including TEXT and SUB parameters. 



Example 1.5 

Specifying substitution length — In all the examples shown, the length 
of the argument being substituted was determined by the number of 
periods in the message text. The number of periods indicated the size 
of the output field, and indirectly determined the exact size of the 
input data area, sometimes it is desirable to determine at execution 
time the size of the input data area. 

These sizes can be specified with the CHARA, CHAR8A, and HEX4A 
conversion types. 

The following substitution list might appear in a LINEDIT macro: 

SUB= (CHARA, LOC, HEX 4A, (3)) 

When specified in this manner, the lengths of the input data fields 
are determined by the number of periods in the message text. To specify 
the length of the input data field, the following alternative form may 
be used: 

SOB= (CHARA, (LOC, (4)) ,HEX4A, ((3) , (5) ) ) 

In the latter format, where each substitution pair has the form 
"type, (address, length) ", register 4 is specified as containing the 
length of the data area at location LOC, and register 5 is specified as 
containing the length of the data area pointed to by register 3. 
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Example 16 

Specifying a length is particularly useful in the special case where 
only one character is to be changed in a CHAHA substitution. To do 
this, two periods iust be coded into the Message, and a length of one 
■ust be specified, as in the example: 

LINEDIT TEXT-' ILLEGAL BODE LETTER ..', 
SDB= (CHARA, (PLIST+24, 1) ) 

The single letter (length=1) at location PLIST+24 is substituted into 
the field consisting of two periods. 

Note: Mo matter what input length is specified, the final substituted 
result cannot be longer than the number of periods in the message text. 
If the input field length and the output length (specified by the number 
of consecutive periods) conflict, the output length will govern, and the 
input length will be truncated accordingly. 



Appendix D: CBS Bacro Instructions 389 



PRINTL MACRO 
PRINTL Macro 

PURPOSE : 

The PRINTL macro causes a line to be written to a virtual printer. 

FORMAT: 



| [label] | PRINTL | line [, length] [ ,ERROR=erraddr ] | 

i 1 



label 



is an optional statement label. 



line specifies the line to be printed. It may be in one of three 
forms: 

'linetext' text enclosed in quote marks. 

lineaddr the symbolic address of the line. 

(reg) a register containing the address of the line. 



length specifies the length of the line to be printed* If omitted, 
133 is assumed unless the text is enclosed in quotes. In this 
case, the number of characters between the quotes is used. 
The length may be specified in two ways: 



(reg) 



a register containing the length. 

a self-defining term indicating the length. 



erraddr specifies the address of an error routine to be given control 
if an error is encountered. If ERRORS is not coded, control 
returns to the next sequential instruction in the calling 
program if an error occurs, as it does if no error occurs. 

OSAGE: 

The PRINTL macro causes the specified line to be written to the printer. 
The maximum length allowed is 151 characters if printing on a virtual 
3211 or 133 characters if printing on a virtual 1403. The first 
character in the line is used as the carriage control character. It 
must be ASCII control character code or a machine carriage control code 
other than X»C1» or X'CS 1 . Since X»C1» and X«C3» are valid for both 
ASCII control character and machine carriage control code, if coded, 
they are interpreted as ASCII control character codes. If a valid 
control character is not specified, a write command with a carriage 
control character to space one line after printing is used. 



The valid ASCII control characters are as follows: 



Meaning 
Space 1 line before printing 
Space 2 lines before printing 
Space 3 lines before printing 
Suppress space before printing 



Character 


Hex Code 


* 


40 





F0 


- 


60 


+ 


4E 
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C h a r a 


cter 


Hpy CCiiK £> 


1 




F1 


2 




F2 


3 




F3 


H 




F4 


5 




F5 


6 




F6 


i 




F7 


8 




F8 


9 




F9 


A 




C1 
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Moan-? n n 

Skip to channel 1 

Skip to channel 2 

Skip to channel 3 

Skip to channel 4 

Skip to channel 5 

Skip to channel 6 

Skip to channel 7 

Skip to channel 8 

Skip to channel 9 

Skip to channel 10 

B C2 Ski™ to channel 1 1 

C C3 Skip to channel 12 

I119.JLC.QN DITION S : 

If an error occurs, processing terminates, and control is passed to 
erraddr (if one was provided) or back to the calling program's next 
sequential instruction. Register 15 contains one of the following error 
codes: 

Code Meaning 

1 Line too long. 

2 Channel 12 punch sensed (virtual 3211 only). 

3 Channel 9 punch sensed (virtual 3211 only). 

4 Intervention required. 

5 Unknown error. 

100 Printer not attached. 

| Note: If the error was a result of sensing a channel 9 or 12 punch while 

| writing to a virtual 3211 using ASA control characters, the operation 

| terminated after the carriage movement but before writing the line. In 

| order to avoid an extra blank line, the print buffer should be rewritten 

| using the 01 channel command code (write without spacing). 
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PUNCHC Macro 

PURPOSE: 

The PUNCHC macro causes a line to be written to a virtual card punch. 

FORMAT : 

| [label] | PUNCHC| line [ ,ERROR=erraddr ] | 

label is an optional statement label. 

line specifies the line to be punched. It may be in one of three 
forms: 

•linetext' text enclosed in quote marks. 

lineaddr the symbolic address of the line. 

(reg) a register containing the address of the line. 

erraddr specifies the address of an error routine to be given control 
if an error is encountered. If ERROR= is not coded, control 
returns to the next sequential instruction in the calling 
program if an error occurs, as it does if no error occurs. 

USAGE : 

The PUNCHC macro causes the specified line to be written to the card 
punch. No stacker selecting is allowed. The line length must be 80 
characters. 

EHR0R_C0N DIT I C NS : 

If an error occurs, processing terminates, and control is passed to 
erraddr (if one was provided) or back to the calling program's next 
sequential instruction. Register 15 contains one of the following error 
codes: 

Code .Meaning 

2 Unit check. 

3 Unknown error. 

100 Punch not attached. 
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RDCARD Macro 

PURPOSE: 

The RDCARD macro causes a line to be read from a virtual card reader. 

FORMAT; 

i 1 

| [label] | RDCARD | buffer [, length] [, ERROR = erraddr] | 



label is an optional statement label. 

buffer specifies the buffer address into which the card is to be 
read. It may be either of two forms: 

bufaddr the symbolic address of the buffer. 

(reg) a register containing the address of the buffer. 

length specifies the length of the card to be read. If omitted, 80 
is assumed. The length may be specified in one of two ways: 

n a self defining term indicating the length, 
(reg) a register containing the length. 

erraddr specifies the address of an error routine to be given 
control if an error is encountered. If ERR0R= is not coded, 
control returns to the next seguential instruction in the 
calling program when an error occurs, as it does if no error 
occurs. 

USAGE : 

The RDCARD macro causes a line to be read from the card reader. No 
stacker selecting is allowed. On return register contains the length 
of the card read. 

ERROR CONDITIONS : 

If an error occurs, processing terminates, and control is passed to 
erraddr (if one was provided) or back to the calling program^ next 
seguential instruction. Register 15 contains one of the following error 
codes: 

Code Meaning 

1 End of file. 

2 Unit check. 

3 Unknown error. 

5 Length not egual to reguested length. 
100 Device not attached. 
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RDTAPE Macro 



PURPOSE : 

The RDTAPE 
drive. 



■aero causes a record to be read froi the specified tape 



FORMAT: 



i 1 

| [label] | RDTAPE | buffer, length [, device] [,MODE=mode] I 

| | | [ ,ERROR=erradr] I 

i 1 



label 
buffer 



| length 
I 



device 



■ode 



is an optional statement label. 

specifies the buffer address into which the record is to be 
read. It may be specified in either of two ways: 

lineaddr the symbolic address of the buffer. 

(reg) a register containing the address of the buffer. 

specifies the length of the record to be read. A 65,535— byte 
record is the largest record that can be read. It may be 
specified in either of two ways: 

n a self— defining term indicating the length. 

(reg) a register containing the length. 

specifies the device from which the line is to be read. If 
omitted, TAP1 is assumed. It may be specified in either of 
two forms: 



TAPn 
cuu 



n indicates the symbolic tape number, 
indicates the virtual device address. 



specifies the number of tracks, density, and tape recording 
technique options. It must be in the following form: 

([track], [density], [trtch]) 

track 7 indicates a 7-track tape (implies density=800 and 
trtch=0) . 
9 indicates a 9-track tape (implies density=800) . 

density 200, 556, or 800 for a 7-track tape. 
800 or 1600 for a 9-track tape. 

trtch indicates the tape recording technique for 
7— track tape. One of the following must be 
specified: 

— odd parity, converter off, translator off. 
OC — odd parity, converter on, translator off. 
OT - odd parity, converter off, translator on. 
E - even parity, converter off, translator off. 
ET — even parity, converter off, translator on. 
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Kots: Houc need not be specified for a read 
operation to a 9-track tape or to an 800 BPI odd 
parity 7-track tape with the Data Converter and 
the Translator off. 

erraddr specifies the address of an error routine to be given control 
if an error is encountered. If EBB0B= is not coded, control 
returns to the next sequential instruction in the calling 
program if an error occurs, as it does if no error occurs. 

OSAGE : 

The BDTAPE macro causes a record to be read from the specified tape 
drive. On return, register and the eighth word of the parameter list 
contain the number of bytes read. 

IRS OIL CONDITIO NS : 

If an error occurs, processing terminates, and control is passed to 
erraddr (if one was provided) or back to the calling program's next 
sequential instruction. Register 15 contains one of the following error 
codes: 

Code Jjeaninq 

1 Invalid function or parameter list. 

2 End-of-file or End-of-tape. 

3 Permanent I/O error. 

4 Invalid device id. 

5 Tape not attached. 
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RDTERM Macro 

PURPOSE: 

The RDTERM macro causes a line to be read from the user's terminal. 

FO RM AT : 

i 1 

III r r nl 

| | [label] | RDTERM | buffer [ r EDIT=code] [LENGTH=length ] | ATTREST= | YES | | | 
till I |N0"||| 

ill L L JJ| 

i i 

label is an optional statement label. 

buffer specifies the address of a 130-character buffer into which the 
line is to be read. It may be either of two forms: 

lineaddr the symbolic address of the buffer. 

(reg) a register containing the address of the buffer. 

code specifies the type of editing, if any, to be performed on the 
input line. If this is not coded, YES is assumed. 

NO indicates that a logical line is to be read and no 
editing is to be done. 

PAD reguests that the input line be padded with blanks 
to the length specified. 

UPCASE reguests that the line be translated to upper case. 

YES indicates PAE+UPCASE. 

PHYS indicates that a physical line is to be read. When 
PHYS is specified, the LENGTH and ATTREST operands 
may also be entered. 

length specifies the length of the caller's buffer area. If not 
specified, 130 is assumed. When EDIT=PHYS, as many as 2030 
bytes may be read. 

ATTREST= specifies the handling of an attention signal during a read 

operation. The normal handling (ATTREST=YES) is to restart 

the operation. If EDIT=PHYS and an explicit LENGTH is given, 

: NO may be specified. In these cases, an attention signal is 

treated as a normal end of the operation. 

USAGE: 

The RDTERM macro causes a line to be read from the user's terminal. On 
return, register contains the number of characters read. 

ER R0R_C0NDITI0 NS : 

| When an error occurs, register 15 contains one of the following error 
| codes: 
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RDTEBM MACHO 

I £ode Meaning 

| 2 An invalid parameter was given. 

| 4 The read was terminated by an attention signal. Possible only 
| when ATTREST=NO 
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REGEQU Macro 



PURPOSE: 



The REGEQU macro equates symbolic names to the general- purpose, 
floating-point, and extended-control registers. 

FORMAT: 



| REGEQU | 



USAGE: 

The REGEQU macro causes the following equate statements to be generated. 
The symbolic names may be used as register specifications in assembly 
language statements. The register usage will then appear in the cross 
reference listing. 



General Registers: 



Extended-Control Registers: 



RO 

R1 

R2 

R3 

R4 

R5 

R6 

R7 

R8 

R9 

R10 

R11 

R12 

R13 

R14 

R15 



FO 
F2 
F4 
F6 



EQU 





EQU 


1 


EQU 


2 


EQU 


3 


EQU 


4 


EQU 


5 


EQU 


6 


EQU 


7 


EQU 


8 


EQU 


9 


EQU 


10 


EQU 


11 


EQU 


12 


EQU 


13 


EQU 


14 


EQU 


15 


Registers 


EQU 





EQU 


2 


EQU 


4 


EQU 


6 



CO 


EQU 





C1 


EQU 


1 


C2 


EQU 


2 


C3 


EQU 


3 


C4 


EQU 


4 


C5 


EQU 


5 


C6 


EQU 


6 


C7 


EQU 


7 


C8 


EQU 


8 


C9 


EQU 


9 


C10 


EQU 


10 


C11 


EQU 


11 


C12 


EQU 


12 


C13 


EQU 


13 


C14 


EQU 


14 


C15 


EQU 


15 
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TAPECTL Macro 

PURPOSE: 

The TAPECTL macro causes the specified tape to be positioned according 
to the specified function code. 

FORMAT: 

i 1 

| [label] | TAPECTL |f unction [ , device ][ ,MODE=mode][ ,ERROR=erraddr ]| 
i i 

label is an optional statement label. 

function specifies the control function to be performed. It must be 
one of the following codes: 

Code Action 

REfi Rewind the tape. 

RUB Rewind and unload the tape. 

ERG Erase a gap. 

BSR Backspace one record. 

BSF Backspace one file. 

FSB Forward space one record. 

FSF Forward space one file. 

HTM Write a tape mark. 

device specifies the tape on which the control operation is to be 
performed. If omitted, TAP1 is assumed. It may be in either 
of two forms: 

TAPn n indicates the symbolic tape number. 

cuu indicates the virtual device address. 

mode specifies the number of tracks, density, and tape recording 
technigue options. It must be in the following form: 

([track], [density], [trtch]) 

track 7 indicates a 7-track tape (implies density=800 and 
trtch=0) . 
9 indicates a 9— track tape (implies density=800) . 

density 200, 556, or 800 for a 7-track tape. 
800 or 1600 for a 9-track tape. 

trtch indicates the tape recording technigue for 
7— track tape. One of the following must be 
specified : 

- odd parity, converter off, translator off. 
OC - odd parity, converter on, translator off. 
OT - odd parity, converter off, translator on. 
E — even parity, converter off, translator off. 
ET - even parity, converter off, translator on. 

erraddr specifies the address of an error routine to be given control 
if an error is encountered. If ERROR 3 is not coded, control 
returns to the next seguential instruction in the calling 
program if an error occurs, as it does if no error occurs. 
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OSAGE: 

The TAPECTL macro causes the control operation to be performed on the 
specified tape drive. 

BBBOB,, CONDITIONS : 

If an error occurs, processing terminates, and control is passed to 
erraddr (if one was provided) or back to the calling program's next 
sequential instruction. Register 15 contains one of the following error 
codes: 

Code Meaning 

1 Invalid function or parameter list. 

2 End-of-file or End-of-tape. 

3 Permanent I/O error. 

4 Invalid device id. 

5 Tape is not attached. 

6 Tape is file protected. 
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WAITD Macro 



POBPOSE: 



The 1AITD macro causes the program to wait until the next interrupt 
occurs for the specified device. 

FORMAT: 



| [label] | WAITD | device. ..[ , devicen ] [ ,Error=erraddr ] | 



label 
devicen 



is an optional statement label. 

specifies the device (s) to be waited for. One 
following may be specified: 



of the 



symn indicates the symbolic device name and number, 
where: 

sym is CON, DSK, PRT, PON, RDR, or TAP. 

n indicates the device number. 

user a name of up to four characters specified in a 
previous HNDINT macro. 

specifies the address of an error routine to be given control 
if an error is encountered. If ERROR= is not coded, control 
returns to the next seguential instruction in the calling 
program if an error occurs, as it does if no error occurs. 



erraddr 



OSAGE: 

The WAITD macro causes the program to wait for an interrupt from one of 
the specified devices. It should be issued to ensure completion of an 
I/O operation. If an interrupt has been received and not processed from 
a device specified in the WAITD macro (the when parameter in the HNDINT 
macro had to be WAIT) the interrupt for the device will be entered. 
When the interrupt has been completely processed, control will be 
returned to the caller with the name of the interrupting device in 
Register 1. If an interrupt has been received and processed from a 
device specified in the WAITD macro (the when parameter in the HNDINT 
macro has to be ASAP) the wait condition is considered satisfied and 
return to the caller is made as previously described. 

An interrupt received from a device specified ASAP in an HNDINT macro 
will be handled. Processing this interrupt will satisfy a WAITD issued 
later for that device. 

The interrupt routine determines if an interrupt is considered 
"processed" or if more interrupts are necessary to satisfy the wait 
condition. For additional information see the HNDINT macro 
documentation. 



ERROR CONDITIONS : 

When an error is detected, register 15 
invalid device number was specified. 



contains a 1 to indicate that an 
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WAITT Macro 



PURPOSE: 



The WAITT macro causes the program to wait until all of the pending I/O 
operations to the user's terminal are completed. 

FORMAT: 



i — — 1 

| [label] I WAITT | 

« ■ 1 

label is an optional statement label. 

OSAGE: 

The WAITT macro is used to synchronize terminal I/O operations. 

ERROR,, CONDITIONS : 

None. 
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WRTAPE Macro 



PURPOSE: 

The WRTAPE macro causes a record to be written on the specified tape 
drive. 

FORMAT; 

i 1 

| [label] | WRTAPE | buffer, length [ , device] | 

| | | [,MODB=mode] [,ERROR=ERRADDR] | 

i i 



label 
buffer 



length 



device 



■ode 



is an optional statement label. 

specifies the address of the record to be written. It may be 
in either of two forms: 

lineaddr the symbolic address of the line. 

(reg) a register containing the address of the line. 

specifies the length of the line to be written. It may be 
specified in either of two ways: 



(reg) 



a self-defining term indicating the length, 
a register containing the length. 



specifies the device to which the record is to be written. If 
omitted, TAP1 is assumed. It may be in either of two forms; 

TAPn n indicates the symbolic tape number. 

cuu indicates the virtual device address. 

specifies the number of tracks, density, and tape recording 
technique options. It must be in the following form: 

([track], [density], [trtch]) 

track 7 indicates a 7— track tape (implies density=800 and 
trtch=0). 
9 indicates a 9— track tape (implies density=800) . 

density 200, 556, or 800 for a 7-track tape 
800 or 1600 for a 9-track tape. 

trtch indicates the tape recording technigue for 
7— track tape. One of the following must be 
specified: 

— odd parity, converter off, translator off. 
OC - odd parity, converter on, translator off. 
OT — odd parity, converter off, translator on. 
E — even parity, converter off, translator off. 
ET — even parity, converter off, translator on. 

erraddr specifies the address of an error routine to be given control 
if an error is encountered. If ERR0R= is not coded control 
returns to the next sequential instruction in the calling 
program if an error occurs, as it does if no error occurs. 
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OSAGE : 

The WRTAPE macro causes a record to be written to the specified tape 
drive. 

ISSOB-CONDI T I NS : 

If an error occurs, processing terminates, and control is passed to 
erraddr (if one was provided) or back to the calling program's next 
sequential instruction. Register 15 contains one of the following error 
codes: 

£2ils !?.§anin(j 

1 Invalid function or parameter list. 

2 End-of-tape or End-of-file. 

3 Permanent I/O error. 

4 Illegal device id. 

5 Tape not attached. 

6 Tape is file protected. 
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WRTERM Macro 

PURPOSE : 

The WRTERM macro causes a line to be displayed at the user's terminal, 

FORMAT: 



I 1 

| [label] | WRTERM | line [, length] [ f EDIT=code ] | 
| | | [ ,COLOR=color ] | 



label is an optional statement label. 



line specifies the line to be displayed. It may be one of three 
forms: 

•linetext' text enclosed in quote marks. 

lineaddr the label on the statement containing the line. 

(reg) a register containing the address of the line. 

length specifies the length of the line. If the line is specified 
within quote marks in the macro, the length parameter may be 
omitted. The length may be specified in either of two ways: 

n a self defining term indicating the length. 

(reg) a register containing the length. 

code specifies whether the line is to be edited: 

YES indicates that trailing blanks are to be removed and a 
carriage return added to the end of the line. 

NO indicates that trailing blanks are net to be removed and 
no carriage return is to be added. 

I LONG indicates the line may exceed 130 bytes, and is to be 

| transmitted from the caller's buffer area. No editing is 

| performed. 

color indicates in which color the line is to be typed if the 
typewriter terminal has a two-color ribbon: 

B indicates that the line is to be typed in black. 

R indicates that the line is to be typed in red. 



404 IBM VM/370: Command Language Guide for General Users 



GC20-1804-3 Page Modified by TNL GN20-2659 

WRTERM MACRO 



USAGE : 

The WRTERM macro causes the specified line to be displayed at the user's 
terminal. The maximum line length is 130 characters for a black line 
and 126 characters for a red line. If EDIT=LONG, COLOR must be given as 
'B*. In this case, as many as 1760 bytes may be sent with a single 
WRTERM macro. The caller is responsible for properly embedding terminal 
control characters in the data, and for the integrity of the data from 
issuance of WRTERM until the data has been sent. The WAITT macro may be 
used to ensure that I/O is complete before the buffer is modified. 

IBIOI-CQND I TIO N S : 

None. 
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Figure 47 relates CMS coaaands, method of 
specifying filemode, and the criteria used 
in choosing a disk directory for reading 
and writing. Symbols used in the table 
are: 



Symbol 
command 

fm 



Reading 

N/A 

fm 
*R 

1R 

*cuu 

Writing 

N/A 

fm 
R 

*W 

1W 

cuu 
*WS 

*1 



Meaning 

CMS command name 

Explicit mode letter can be 
specified 

Write disk to Read disk 

Refer to all disks in a set 
search order 

Default mode: let system 
determine the aode 

Null aode; unable to specify mode 
letter in this command 

The criteria for choosing the 
disk from which to read 

Not applicable, coaaand does not 
cause any reading to be done 

Read froa the specified disk 

Refer to all disks in the 
standard search order 

Read only froa the primary disk 

All occurrences of the address 

Indicates criteria for selecting 
the disk to write onto 

Not applicable, command does not 
cause any writing to be done 

Write onto the specified disk 

Write onto the disk from which a 
file was read (or its parent) 

Choose any read/write disk in the 
standard search pattern 

Attempt to write onto the primary 
disk 

Write to the specified address 

First read/write disk with enough 
space 

First disk where file is found if 
disk is in read/write status 



r 

| Command 


Filemode 


| Reading 


— ., 

| Writing | 


| ACCESS 


mode 
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1 fa 

| 1R 


I N/A I 
I N/A I 


| ASM3705 


- 


I *R 
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| BASIC 
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I fm 
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*R 


N/A | 
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| CONVERT* 
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fa 
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| COPYFILE 


fa 
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fa 
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| DEBUG 
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| DIRECT 








| DISK DUMP 
| DISK LOAD 


fa 

* 
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1R 
N/A 
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N/A | 
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1W I 


| EDIT 


fa 

* 
d 
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*R 
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« I 
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| ERASE 


fa 

* 
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| EXEC 
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| FILEDEF 
| FORMAT | 
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| FORTHX 1 | 
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| FORTRAN 1 | 
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Figure 48 shows filetypes that have special uses in CMS. 
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control language | 
statements | 




COBOL* 


output 


fn 






Object code | 




GEN3705 


output 


fn(Ln) 


F 


| 80 


Linkage editor | 
control statements | 
for 3704/3705 | 
control programs | 




INCLUDE 


input 


fn 






Object code | 




LKED 


input 


fn | 






Object code and | 
LKED control cards | 




LOAD 


input 


fn 






Object code | 




PLIOPT 1 


output 


fn 






Object code | 




TXTLIB 


input 


fn | 






Object code | 




GOFORT 1 


output 


fn | 






Object file | 




FORTGI 1 


output 












FORTHX 1 


output 












TESTFORT 1 


input 










TXTLIB 


GLOBAL 


library 


fn 


Libr 


ary contains 


Object decks | 




TXTLIB 


output 


fn | 


dictionary and 












mem 


bers j 




UPDATE 


UPDATE 


input 


fn 


F 


I 80 | 


UPDATE control | 
c aT "ds ' 


UPDLOG 


UPDATE 


output 


fn 


F 




UPDATE log | 


UPDATE 


UPDATE 


input | 


fn | 


F 


I 80 


Local updates | 


VSBASIC 


VSBASIC 


input 


fn | 


F 


| <256 


VSBASIC language | 
source statements | 


VSBDATA | 


VSBDATA | 


execution 
time files | 


fn 


V 


| <140 


VSBASIC user input/| 
output files | 


*IBH Progra 


im Products 
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* command 17 
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summary 245 



&ARGS control statement, of EXEC command 

128 
6BEGP0NCH control statement, of EXEC 

command 128 
&BEGSTACK control statement, of EXEC 

command 128 
SBEGTYPE control statement, of EXEC command 

128 
SCONCAT built-in function, of EXEC command 

130 
SCONTINOE control statement, of EXEC 

command 128 
8C0NTR0L control statement, of EXEC command 

128 
SDATATYPE built-in function, of EXEC 

command 130 
SEND control statement, of EXEC command 

128 
&ERR0R control statement, of EXEC command 

128 
SEXIT control statement, of EXEC command 

129 
8G0T0 control statement, of EXEC command 

129 
&IF control statement, of EXEC command 129 
SLENGTH built-in function, of EXEC command 

130 
6LITERAL built-in function, of EXEC command 

130 
&LOOP control statement, of EXEC command 

129 
SPUNCH control statement, of EXEC command 

129 
&READ control statement, of EXEC command 

129 
6SKIP control statement, of EXEC command 

129 
SSPACE control statement, of EXEC command 

129 
&STACK control statement, of EXEC command 

129 
SSUBSTR built-in function, of EXEC command 

130 
&TIME control statement, of EXEC command 

130 
STYPE control statment, of EXEC command 

130 
Svariable control statement, of EXEC 

command 128 



$DUP subcommand, of EDIT command 123 
$MOVE subcommand, of EDIT command 123 



/* control card, for the CMS batch facility 

358 
/JOB control card, for the CMS batch 

facility 358 
/SET control card, for the CMS batch 

facility 359 



? subcommand, of EDIT command 123 
?, use of with the FILEDEF DISK operand 
138 



#, line end logical editing symbol 49 
#CP command 

described 250 

summary 245 



a, symbol delete logical editing symbol 49 



", escape symbol logical editing symbol 49 



ABBREV operand 

of CMS QUERY command 185 

of CMS SET command 198 
abbreviations for commands 19 

controlling 198 
ABEND, problem program 353 
ACCESS command 29 

CMS responses to 81 

described 78 

ERASE option 79 

examples of 80 

NODISK option 79 

NOPROF option 79 

summary 73 

to access a disk you defined via DEFINE 
29 

used after linking to a virtual disk 29 

used to alter the search order for 
virtual disks 30 

used to change read/write status of a 
virtual disk 31 

used with OS data sets and DOS files 40 
access mode of virtual disks 29 
accessing a read-only OS disk 80 
accessing CMS with no virtual disks 
attached to your virtual machine 79 
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accessing virtual disks 29 
accessing your virtual machine 29 
accounting information 

displaying 312 

for the CBS batch facility 358 
ACNT command, summary 245 
ACHT operand, of CP SET command 312 
acquiring disk space 78 
ADD operand 

of the MACLIB command 170 

of TXTLIB command 220 
adding records to a file 118 
adding to a file, using EDIT command in 

INPUT mode 16 
adding to a macro library 170 
adding to a TEXT library 220 
adding to the EXEC file created using 

LISTPILE command output 158 
A-disk 27 

accessed after IPL CMS 80 
ADSTOP command 

described 252 

OFF operand 252 

summary 245 
ALIGN option, of ASSEMBLE command 85 
alignment of boundaries in assembler 

program statements 85 
ALL operand 

of (CP) QUERY command 298,298 

of CHANGE command 256 

of PURGE command 295 

of the TRANSFER command 338 

of TRACE command 335 
ALLOC option, of LISTFILE command 158 
ALOGIC option, of the ASSEMBLE command 82 
ALTER subcommand of EDIT command 119 
altering characters in a record 119 
altering constants using LOAD command 166 
altering instructions using LOAD command 

166 
altering read/write status of virtual disks 

30 
altering records of a file 119 
altering the attributes of a virtual 

printer file 256 
altering the attributes of a virtual punch 

file 256 
altering the attributes of a virtual reader 

file 256 
altering the logical editing symbols 331 
altering the search order of virtual disks 

30 
altering your virtual machine environment 

264 
alternating operating system execution 65 

OS job stream 66 

VM/370 directory 67 
analysis, system and hardware, commands 

used for 350 
annotating your console sheet 249 
Any user, described 242 
APL character translation tables, 

controlling 331 
APL operand, of TERMINAL command 332 
APPEND option 

of COPYFILE command 96 

of LISTFILE command 158 
appending one file to another 91 



ASM3705 command, summary 73 
ASSEMBLE command 13 

ALIGN option 85 

ALOGIC option 82 

BUFSIZE option 85 

DECK option 84 

described 82 

DISK option 84 

ESD option 83 

example of 57 

FLAG option 83 

LIBMAC option 83 

LINECOUN option 83 

LIST option 83 

listing control options for 82 

MCALL option 83 

MLOGIC option 83 

NOALIGN option 85 

NOALOGIC option 83 

NODECK option 84 

NOESD option 83 

NOLIBMAC option 84 

NOLIST option 83 

NOMCALL option 83 

NOMLOGIC option 83 

NONUMBER option 85 

NOOBJECT option 84 

NOPRINT option 84 

NORENT option 86 

NORLD option 83 

NOSTMT option 85 

NOTERM option 85 

NOXREF option 84 

NUMBER option 85 

OBJECT option 84 

PRINT option 84 

RENT option 86 

RLD option 83 

STMT option 85 

summary 73 

SYSPARM option 86 

SYSTERM listing 85 

TERMINAL option option 85 

TEST option 84 

used with OS data sets and DOS files 4 

XREF option 84 
ASSEMBLE filetype 36 
assembler diagnostic messages, controlling 

the listing of 83 
assembler inner macro instructions, 

controlling the listing of 83 
assembler listing, controlling the 

production of 83 
assembler macro instructions, controlling 

the listing of 83 
assembler relocation dictionary, 

controlling the listing of 83 
assembler 

conditional assembly statements, 
controlling the listing of 82 

controlling number of lines printed by 
83 

controlling the listing of the External 
Symbol Dictionary (ESD) 83 

output control options for 83 

overriding CMS file defaults 86 

under CMS 13 

using under CMS 82 
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assembling a program file, example of 57 
assembling a program using OS macros 39 
ASSIST operand, of CP SET command 314 
asterisk '*t used in the fiiemode field 

44 
ATTACH command, summary 245 
attaching devices to virtual machine 59 
attention handling, terminal control of 

331 
attention interrupt 

effect on virtual console in CP mode 25 

effect on virtual console in VM mode 24 

entering from your virtual console 254 

for a virtual machine 309 
Attention key 

how to use 22 

used to interrupt execution of a command 
22 

used to switch command environments 22 
ATTN command 

described 254 

summary 245 
ATTN operand, of TERMINAL command 333 
attributes of a spool file, changing 256 
attributes of virtual devices, modifying 

318 
AUTO option 

of INCLUDE command 151 

of LOAD command 162 
AUTOREAD option, of CMS SET command 199 
AUTOSAVE subcommand, of EDIT command 119 
auxiliary directory, creation of 145 



B 

BACKSPAC command, summary 245 

BACKWARD subcommand, of EDIT command 119 

batch facility ID card 357 

batch facility 

CMS, using 357 

command restrictions for 360 

described 357 

input to 358 

output 360 
BCD characters, converting to EBCDIC 95 
BDAM OS access method 41 
B-disk 27 
BEGIN command 

described 255 

summary 245 

used with the DISCONN command 271 
beginning execution with an INCLUDE command 

151 
blanks, as delimiters 16 
blip characters 

for your virtual machine 197 
displaying 184 
BLIP option 

for CMS QUERY command 184 

for CMS SET command 197 
BLKSIZE option, of FILEDEP command 136 
BLOCK option, of FILEDEF command 136 
blocksize, for CMS files 137 
BOTH operand, OF TRACE command 335 
BOTTOM subcommand, of EDIT command 53,119 
boundary alignment, of statements in an 
assembler program 85 



BRANCH operand, of TRACE command 335 

branches, tracing 334 

BREAK subcommand, of DEBUG command 115 

buffer size, assembler, controlling size of 

85 
BUFSIZE option, of ASSEMBLE command 85 



Cancel key 59 

carriage control characters for PRINT 

command, specifying 179 
CASE subcommand, of EDIT command 119 
CAW (Channel Address Word) 114 
CAW operand, of DISPLAY command 274 
CAW subcommand, of DEBUG command 115 
CC option, of PRINT command 179 
CCW operand, of TRACE command 335 
CCW translation, controlling 313 
C-disk 27 
CHANGE command 

ALL operand 256 

CLASS operand 256 

COPY operand 256 

described 256 

DIST operand 257 

HOLD operand 256,258 

NAME operand 257 

NOHOLD operand 257 

PRINTER operand 256 

PUNCH operand 256 

READER operand 256 

summary 245 
CHANGE option, of FILEDEF command 135 
CHANGE subcommand, of EDIT command 54,120 
changing extended control registers in your 

virtual machine 325 
changing floating-point registers in your 

virtual machine 325 
changing general registers in your virtual 

machine 325 
changing records in files 118 
changing the attributes of a spool file 

256 
changing the contents of a record 54 
changing the contents of control words 114 
changing the filename of a spool file 257 
changing the Program Status Word (PSW) in 

your virtual machine 325 
changing the spool class of a file 256 
changing the spoolid of a file 256 
changing virtual storage locations in your 

virtual machine 324 
Channel Address Word (CAW) 114 

displaying 272 
Channel Status Word (CSW) 114 

displaying 272 
CHANNELS operand 

of (CP) QUERY command 297 

of DEFINE command 265 
channel-to-channel adapters, virtual, 

connecting 261 
character delete logical editing symbol 49 
character set 17 
character string translation 120 
character strings, replacement of 54 
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character translation 91 
character translation tables, APL, 

controlling 331 
characters of a record, moving to different 

positions 91 
CHARDEL operand, of TERMINAL command 331 
CLASS operand 

of (CP) QUERY command 299 

of CHANGE command 256 

of PURGE command 295 

of SPOOL command 319 

of the TRANSFER command 338 
class 

privilege 

for CP commands 13 
for CP commands 243 

spool, changing for a file 256 

virtual device spool, modifying 318 
CLEAR operand 

of FILEDEF command 133 

of IPL command 282 

of the SYSTEM command 327 
CLEAR option 

of INCLUDE command 150 

of LOAD command 161 

of SYNONYM command 208 
clearing a file definition set by FILEDEF 

138 
clearing interrupts from a virtual machine 

310 
clearing storage to zeros 150,161,282,327 
clearing synonyms from a synonym table 208 
CLOSE command 

CONSOLE operand 258 

described 258 

DIST operand 259 

NAME operand 259 

NOHOLD operand 258 

PRINTER operand 258 

PUNCH operand 258 

PURGE operand 259 

READER operand 258 

summary 245 
CLOSE operand, of SPOOL command 321 
closing a virtual device 318 
closing files 258 

CMS (see Conversational Monitor System) 
CMS assemble file defaults 86 
CMS command language, basic description of 

13 
CMS commands 

immediate 77 

summary of 73 

using READCARD command 46,62 

using TAPE command 45 

using TAPPDS command 45 
CMS Editor 

described 52 

used to create files 33 
CMS files 

relationship to DOS files 132 

relationship to OS data sets 132 
CMS libraries 18 

CMS subcommand, of EDIT command 120 
CMSBATCH command 

described 88 

summary 73 
COBOL command, summary 73 



COL option, of TYPE command 224 
C0L1 option, of TAPPDS command 218 
command environment 
CP 15 
defined 15 
switching 15 
VM 15 
command execution, halting 238 
command language 

CMS, basic description of 13 
CP, basic description of 13 
command name 16 
command operands 16 
command options 17 

defined 17 
command search order 
CMS 

for filetype EXEC 20 
for filetype MODULE 20 
levels of search in 21 
nucleus resident commands 20 
transient area commands 20 
command, mode, EDIT 52 
commands 

abbreviation of 19,69 
CMS 

search order for 20 
summarized 73 
CP, privilege classes for 13 
interrupting the execution of 22 
minimum truncation for 19,69 
notational conventions for 69 
summary of use 341 
system-defined 15 
truncation of 19 

used for debugging, summary of 343 
used for disk control, summary of 345 
used for testing, summary of 343 
used to control a terminal session, 

summary of 341 
used to control a virtual machine, 

summary of 346 
used to develop programs, summarized 

342 
used to update files, summary of 344 
user-defined 15 
comments control statement, for UPDATE 

command 230 
comments, how to write 17 
COMP operand, of MACLIB command 170 
compacting members in a macro library 170 
COMPARE command 
described 89 
summary 73 
comparison of CP and CMS debugging 

facilities 356 
compiling, loading, and starting execution 

of a file 195 
compressing a file 91 
COMPSWT, CMS macro instruction 365 
CONCAT option, of FILEDEF command 135 
concatenating data sets 135 
concatenating files 135 
conditional assembly statements, assembler, 

controlling the listing of 82 
configurating virtual machines 
addresses 67 
device types 67 
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connecting 

a remote terminal to a virtual machine 
269 

virtual channel-to-channel adapters 261 
console input/output, terminating 318 
CONSOLE operand 

of (CP) QUERY command 297 

of CLOSE command 258 

of DEFINE command 261 

of SPOOL command 319 
console 

sheet, annotation of 249 

spool file 12 
modifying 318 

spooling, controlling 318 

virtual, what you should know before 
using 48 
constants, altering using LOAD command 166 
CONT operand, of SPOOL command 319 
continuation mark, example of entering 56 
continuous reading of an entire file 318 
control card 

/*, for the CMS batch facility 358 

/SET for the CMS batch facility 359 
control functions 

for tapes 213 

setting for your virtual machine 312 
Control Program, basic description of 11 
control statements 

for DDR command 104 

for the UPDATE command 226 
control words, changing and examining the 

contents of 114 
controlling 

a terminal session, summary of commands 
used 341 

devices on your virtual machine 13 

listing of conditional assembly 
statements 82 

number of lines printed by the assembler 
83 

program development, summary of commands 
used for 342 

the listing of assembler diagnostics 
messages 83 

the listing of inner macro instructions 
83 

the production of the assembler listing 
83 
Conversational Monitor System 

basic description of 11 

card reader 46 

tape handling 45 

transferring reader files 46 

unit record support 46 
CONVERT command, summary 73 
converting 

BCD characters to EBCDIC characters 95 

key punch characters 91 
COPY function control statement, of DDR 

command 107 
COPY operand 

of CHANGE command 256 

of SPOOL command 321 
COPYFILE command 

APPEND option 96 

described 91 

EBCDIC option 95 



examples of 99 

FILL option 96 

FOR option 93 

FRLABEL option 93 

FROM option 93 
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LOWCASE option 95 

LRECL option 93 

NEWDATE option 93 

NEWFILE option 95 

NOPROMPT option 93 

NOSPECS option 98 

NOTRUNC option 94 

NOTYPE option 93 

OLDATE option 93 

OVLY option 96 

PACK option 94 

PROMPT option 93 

RECFM option 93 

REPLACE option 95 

responses 101 

specification list 97 

SPECS option 96 

summary 73 

TOLABEL option 93 

TRANS option 98 

TRUNC option 93 

TYPE option 93 

UNPACK option 95 

UPCASE option 95 
copying 

data from one file to another 91 

files from one device to another 104 
correcting errors on an input line 48 
COUNT option, of DDR command TYPE/PRINT 

function control statement 110 
COUPLE command 

described 261 

summary 245 
CP (see Control Program) 
CP and CMS commands, entering 16 
CP command 

described 263 

description of 103 

entering from the VM environment 263 

environment 15 

privilege classes for 13,241 

privilege classes, described 243 

summary 73,245 
CP mode, on virtual console 59 
CP/CMS, as an integrated command language 

15 
CPEREP command, summary 73 
creating 

a file 52 

using the Editor in INPUT mode 16 

a load map of a file 162 

a map of a load module 151 

a map of files in a TEXT library 221 

a program file, example of 56 

a SYNONYM file 20 

an auxiliary directory 145 

an EXEC file containing of output from 
the LISTFILE command 158 

files 33,118 

files on disk 189 

macro libraries 170 
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reference information about members of 

macro library 170 
user file directory (ACCESS command) 78 
cross-reference table, assembler, 

controlling the listing of 84 
CSECTs, duplicate, for the LOAD command 

163 
CSW (Channel Status Word) 114 
CSW operand 

of DISPLAY command 274 
of TRACE command 335 
CSW subcommand, of DEBUG command 115 
CTCA operand, of DEFINE command 265 
CTL option 

of UPDATE command 226 

detailed description of 232 
current line pointer 119 
described 53 
moving dovn in a file 54 
moving up in a file 54 
cylinders, counting number of on a virtual 
disk 142 



DAM DOS access method 41 

DASD Dump Restore program, invoking via the 
DDR command 104 

DASD operand, of (CP) QUERY command 297 

data extents for DOS files 41 

data set keys 41 

data set labels 41 

data sets, concatenating 135 

data, overlaying in a file 91 

DATE option, of LISTFILE command 158 

DCP command, summary 245 

D-disk 27 

accessed after IPL CHS 80 

DDR command 

COPY function control statement 107 
COUNT option of TYPE/PRINT function 

control statement 110 
description of 104 

DUMP function control statement 107 
example of TYPE/PRINT output 111 
GRAPHIC option of TYPE/PRINT function 

control statement 110 
HEX option of TYPE/PRINT function 

control statement 110 
INPUT control statement 105 
PRINT function control statement 109 
responses 110 

RESTORE function control statement 107 
summary 73 

SYSPRINT control statement 106 
TYPE function control statement 109 
used with OS data sets and DOS files 40 

DDR control statements 104 

DEBUG command 13 
described 114 
summary 73 

DEBUG subcommand environment 16 

DEBUG subcommands, listed 115 

debugging 

a program using VM/370 351 
facilities of CP and CMS, compared 356 
programs using the DEBUG command 114 
summary of commands used for 343 



DECK option, of the ASSEMBLE command 84 
default file attributes, summarized 405 
DEFINE command 29 

adding temporary disks 31 

CHANNELS operand 265 

CONSOLE operand 264 

CTCA operand 265 

described 264 

GRAF operand 265 

LINE operand 265 

PRINTER operand 264 

PUNCH operand 264 

READER operand 264 

STORAGE operand 266 

summary 245 

TIMER operand 265 

T2305 operand 266 

T2314 operand 266 

T2319 operand 266 

T3330 operand 266 

T3340 operand 266 

use 59 

used to define a temporary virtual disk 
27 

1403 operand 265 

3211 operand 265 
DEFINE subcommand, of DEBUG command 115 
defining 

a virtual device 264 

a virtual I/O device for your virtual 
machine 265 

DOS files under CMS 132 

OS data sets under CMS 132 

temporary virtual disks 29 

virtual disk addresses 28 
DEL operand 

of MACLIB command 170 

of TXTLIB command 220 
delete control statement, for UPDATE 

command 229 
DELETE subcommand, of EDIT command 120 
deleting 

a line from a file 54 

files from virtual disk 125 

from a TEXT library 220 

members of a macro library 170 

records from a file 118,229 
delimiting fields of command line 17 
DEN option 

of FILEDEF command 135 

TAPE command 214 
density of tapes, specifying 214 
description of OS data sets, listing of 

155 
DETACH command 

described 267 

summary 245 
detaching a device from your virtual 

machine 267 
determining the status of devices on your 

virtual machine 297 
developing program files, summary of 

commands used for 342 
device-end interrupt pending for a virtual 

device, specifying 308 
devices 

attaching to virtual machine 59 

defining for virtual machine 59 
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linking to 59 

linking to a virtual machine 284 

■aking ready 59 

tape devices for virtual machine 60 

virtual 

purging from your system 295 
simulating not ready status for 293 
DIAL command 

described 269 

summary 245 
dictionary, for a TEXT library 221 
DIRECT command, summary 73 
directory, VM/370 user 11 
DISABLE command, summary 245 
disabled loop, in a problem program 353 
disabled wait, for a problem program 354 
DISCONN command 64 

described 271 

HOLD operand 271 

summary 246 
disconnecting 

the terminal 64 

your virtual console 271 

your virtual machine 288 
disk addresses, for virtual disks 27 
DISK command 

described 116 

DUMP operand 116 

LOAD operand 116 

summary 73 
disk control, summary of commands used for 

345 
disk files 

comparison of formats for 89 

created from OS tapes 217 

punching to a virtual card punch 116 
disk identifier, for a virtual disk 27 
disk letter, of filemode field 43 
DISK operand 

of CHS QOEBY command 186 

of FILEDEF command 133 
interactive use of 138 
DISK option 

of HACLIB command 171 

of QUERY command 32 

of TAPE command 214 

of the ASSEMBLE command 84 

of UPDATE command 226 
disk space, acguiring 78 
disk storage capacity, displaying status of 

186 
disks 

determining status of 184 

OS, reading OS data sets on 40 

releasing from your virtual machine 192 

virtual 

deleting files from 125 
formatting 51 
initializing 142 
DISP option, of FILEDEF command 134 
DISPLAY command 

CAH operand 274 

CSW operand 274 

described 272 

PSW operand 274 

summary 246 
displaying 

accounting information 312 



BLIP characters for your virtual machine 

184 
Channel Address Word (CAW) 274 
Channel Status Word (CSW) 274 
extended control registers 273 
filenames on a tape disk 213 
first record of a file 53 
floating-point registers 273 
general registers 273 
last record of a file 53 
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map of a load module 151 

names of members of a library 224 

Program Status Word (PSW) 274 

records in a file 54 

selected positions of a record 224 

virtual storage locations 272 
DIST operand 

of CHANGE command 257 

of CLOSE command 259 
distribution code, for an output file 257 
DHCP command, summary 246 
DOS disks 

accessing 80 

formatting of 28 

reading DOS files on 40 
DOS files 

file-id 41 

handled via FILEDEF and MOVEFILE 
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listing of 155 
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reading 40 

restrictions for reading 41 

under CHS 132 

user labels and data extents 41 

with security indicator on 41 
DOS libraries 41 
DOS POWER, spooling in a virtual machine 

63 
DOWN subcommand, of EDIT command 54,120 
DRAIN command, summary 246 
DUMMY operand, of FILEDEF command 133 
DUMP command 

described 277 

summary 246 
DUMP function control statement, of DDR 

command 107 
DUMP operand 

of DISK command 116 

of TAPE command 212 

format of tape created by 215 
DUMP subcommand, of DEBUG command 115 
dumping 

disk files to tape 104 
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DUP option 

of INCLUDE command 151 

of LOAD command 163 
duplicate CSECTs, for the LOAD command 163 
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ECHO command 

described 280 

summary 246 
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EDIT command 13,15 

$D0P subcommand 123 

$H0VE subcommand 123 

? subcommand 123 

ALTER subcommand 119 

AUTOSAVE subcommand 119 

BACKWARD subcommand 119 

BOTTOM subcommand 53,119 

CASE subcommand 119 

CHANGE subcommand 120 

CHS subcommand 120 

DELETE subcommand 120 

described 118 

DOWN subcommand 54,120 

EDIT mode 52 

example of 52 

FILE subcommand 55,120 

FIND subcommand 120 

FHODE subcommand 120 

FNAHE subcommand 120 

FORWARD subcommand 120 

GETFILE subcommand 120 

IHAGE subcommand 120 

INPUT mode 52 

INPUT subcommand 120 

LINEHODE subcommand 120 

LOCATE subcommand 121 

LONG subcommand 121 
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NEXT subcommand 121 

nnnnn subcommand 123 
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PRESERVE subcommand 121 

PROMPT subcommand 121 

QUIT subcommand 121 

RECFH subcommand 121 

RENUM subcommand 121 

REPEAT subcommand 121 

REPLACE subcommand 121 

RESTORE subcommand 121 
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REUSE subcommand 121 

SAVE subcommand 122 

SCROLL subcommand 122 
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SHORT subcommand 122 

STACK subcommand 122 

summary 74 
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TRUNC subcommand 122 
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UP subcommand 54,122 
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VERIFY subcommand 122 
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Y subcommand 122 

ZONE subcommand 122 
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EDIT mode 16 
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EMSG operand, of CP SET command 313 
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enabled loop, in a problem program 354 
enabled wait, for a problem program 355 
END operand, of TRACE command 335 
END option, of TAPPDS command 218 
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a CP command from a CMS virtual machine 
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a CP command from the VM environment 
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ENTRY control card, for the loader 166 
EOF operand, of SPOOL command 320 
EOF option, of TAPE command 214 
EOT option, of TAPE command 214 
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44 
ERASE command 

described 125 
NOTYPE option 125 
summary 74 
TYPE option 125 
ERASE option, of ACCESS command 79 
erasing 

old files 79 

the contents of a virtual disk 28 
error message handling, controlling 313 
error recovery, in batch mode 361 
errors, on an input line, correcting 49 
escape logical editing symbol 49 
ESCAPE operand, of TERMINAL command 332 
ESD option, of the ASSEMBLE command 83 
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EXEC command 13,15,15 
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&BEGPUNCH control statement 128 
SBEGSTACK control statement 128 
&BEGTYPE control statement 128 
SCONCAT built-in function 130 
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determining number of for your virtual 
machine 297 

determining the status of 297 

purging from your system 295 

removing from your virtual machine 267 

simulating not ready status for 293 

specifying a device-end interrupt for 
308 
virtual disk addresses, defining 28 
virtual disk cylinders, counting number of 

142 
virtual disks 

access mode of 29 

accessing 29 
CMS disks 78 

adding temporary disks 31 

addresses of 27 



allocating cylinders for 27 

altering the search order of 30 

CMS 12 

CMS standard search order 30 

CP and CMS access 31 

defined 27 

defining the size of 12 

deleting files from 125 

description of 11 

erasing the contents of 28 

extensions of 30,31 

finding the read/write status of 32 

formatting 28,51 

identifier 27 

initialization of 142 

linking to another user's 29 

master file directory 27 

maximum number allowed 27 

read-only status of 30 

read/write status of 30,31 

releasing 29 

resetting the number of cylinders on 
142 

search order for 30 

temporary, defining 29 

writing a label on 142 
virtual I/O devices 

defining for your virtual machine 265 

spooling to 12 
Virtual Machine (VM) environment, entering 

CP commands from 250 
virtual machine environment, determining 

the status of 184 
Virtual Machine Facility/370, basic 

description of 11 
virtual machine 

activity, tracing 334 

alternating execution of operating 
systems 65 

attaching devices 59 

batch facility, described 357 

components of 11 

configuration, altering 264 

configurations 67 

controlling the devices on 13 

defined 11 

determining general information on the 
status of 297 

device, linking to 284 

disconnecting 288 

disconnecting the terminal 64 

execution 68 
resuming 255 

gaining access to 290 

loading with operating system 50,60 

logging off of 58,288 

logging on 50,290 

operating system, passing parameters to 
282 

placing in a dormant state 317 

printing and punching 63 

reading cards into 62 

setting control functions for 312 

spooling 63 

storing information from 324 

summary of commands used to control 346 

transferring output 65 
VIRTUAL operand, of (CP) QUERY command 297 
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virtual printer (3211), specifying forms 

controls for 287 
virtual printer, spooling to 214 
virtual storage locations 

changing in your virtual machine 325 

printing 277 
virtual system console 

differences from real console 59 

replying to messages 59 
virtual timer, controlling 314 
VM environment 15 

entering a CP command from 263 
VMFDUMP command, summary 76 
VM/370 (see Virtual Machine Facility/370) 
VM/370 directory 11,28 

entry, description of 29 

for alternating operating system 
execution 67 
VSAM DOS access method 41 
VSAM OS access method 41 
VSBASIC command, summary 76 
VSBOTIL command, summary 76 



h 
wait 

disabled, for 
enabled, for 
WAITD, CMS macro 
HAITT, CMS macro 
WARNING command, 
warning messages 
in UPDATE comma 
WNG operand, of 
writing 

cards to a vi 

card reader 

comments in V 

tape files to 

user-defined 

WRTAPE, CMS macr 

WRTERM, CMS macr 

HTM option, of T 



a problem program 354 
a problem program 355 

instruction 400 

instruction 401 

summary 248 

, generation of for errors 
nd execution 226 
CP SET command 312 

rtual disk from a virtual 

116 
M/370 17 

disk 213 
commands 18 
o instruction 402 
o instruction 404 
APE command 214 



XREF option, of the ASSEMBLE command 84 
XTENT option, of FILEDEF command 134 



Y subcommand, of EDIT command 122 
Y-disk 27 

accessed after IPL CMS 80 



ZAP command, summary 76 

Z-disk 27 

zeros, clearing storage to 282,327 

ZONE subcommand, of EDIT command 122 



1 

1403 operand, of DEFINE command 265 

19E virtual disk address 28 

accessed as Y-disk 80 

190 virtual disk address 28 
accessed as S-disk 80 

191 virtual disk address 27 
accessed as A-disk 80 

192 virtual disk address 27 
accessed as D-disk 80 



3211 operand, of DEFINE command 265 
3211 printer, virtual, specifying forms 
controls for 287 



7TRACK option 

of FILEDEF command 135 
of TAPE command 214 

7-track tapes, specifying 214 



X subcommand 

of DEBUG command 115 
of EDIT command 122 



9TRACK option 

of FILEDEF command 135 
of the TAPE command 214 

9-track tapes, specifying 214 
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